API Documentation

Request

POST /api/v1/validate/single
X-API-Key: <your-key>
Content-Type: application/json

{
  "email": "user@example.com",
  "company_id": 1,
  "force_revalidate": false
}

Field	Required	Description
email	Yes	The email address to validate
company_id	No	Company to bill against. Defaults to the key's primary company. Required if the key is assigned to multiple companies.
force_revalidate	No	true to skip the cache and always call the validator, even if a fresh result exists. Default: false

Response

{
  "email": "user@example.com",
  "status": "Valid",
  "raw_status": "ok",
  "source": "elv",
  "cached": true,
  "date_last_validated": "2025-06-01T12:34:56"
}

Field	Type	Description
email	string	The email that was checked
status	string	Valid, Invalid, or Greylist
raw_status	string	The raw status code returned by the validator
source	string	Validation provider used (elv, custom, …)
cached	boolean	true if result was served from the local DB cache
date_last_validated	string (ISO 8601)	When the email was last validated against the provider

Returns the companies your API key is authorized for. Use the id as company_id in other requests.

Request

GET /api/v1/companies
X-API-Key: <your-key>

Response

[
  {"id": 1, "name": "Acme Corp", "slug": "acme-corp"},
  {"id": 3, "name": "Beta Ltd",  "slug": "beta-ltd"}
]

Upload a CSV file with an email column (header must be exactly email). The endpoint returns a job_id immediately; processing runs in the background.

Request — multipart/form-data

POST /api/v1/validate/file?company_id=1&force_revalidate=false
X-API-Key: <your-key>
Content-Type: multipart/form-data

file=@emails.csv   (field name must be "file")

Query param	Required	Description
company_id	No	Company to bill against. Defaults to the key's primary company. Required if the key is assigned to multiple companies.
force_revalidate	No	true to skip cache for all emails in the file. Default: false

Example CSV

email
alice@example.com
bob@example.com
charlie@example.com

Response

{
  "job_id": 42,
  "status": "Processing",
  "total": 3
}

Poll this endpoint until status is Done or Error.

Request

GET /api/v1/jobs/42
X-API-Key: <your-key>

Response — in progress

{
  "job_id": 42,
  "status": "Processing",
  "progress": 65,
  "total": 1000,
  "processed": 650
}

Response — complete

{
  "job_id": 42,
  "status": "Done",
  "progress": 100,
  "total": 1000,
  "processed": 1000
}

Status value	Meaning
Pending	Job queued, not started yet
Processing	Currently being validated
Done	Complete — download results with the endpoint below
Error	Job failed — check error_message field

Returns billing volumes and validation outcome counts for a given period. Available to all API keys — results are automatically scoped to your company. Admin keys additionally receive a full billing breakdown and can query any company via company_id.

Request

GET /api/v1/reports/summary?start_date=2026-03-01&end_date=2026-03-31
X-API-Key: <your-key>

Query param	Type	Description
start_date	YYYY-MM-DD	Start of date range (inclusive)
end_date	YYYY-MM-DD	End of date range (inclusive)
company_id	int	Admin keys only — filter by a specific company. Ignored for standard keys.

Response — standard key

{
  "billed":   2051840,
  "valid":    1894230,
  "invalid":  142518,
  "greylist": 15092
}

Field	Description
billed	Total emails charged for the period
valid	Contacts with validation outcome Valid
invalid	Contacts with validation outcome Invalid
greylist	Contacts with validation outcome Greylist

Response — admin key (full breakdown)

{
  "billed":            2051840,
  "last_called_count": 2051840,
  "fresh_cleaned":     2051453,
  "cross_cache":       387,
  "own_cache":         1517,
  "local_rejections":  133,
  "valid":             1894230,
  "invalid":           142518,
  "greylist":          15092
}

Field	Description
billed	Total charged = fresh_cleaned + cross_cache
last_called_count	Alias for billed (kept for backwards compatibility)
fresh_cleaned	Emails sent to the external validator (billed)
cross_cache	Cache hits from another company's prior validation (billed)
own_cache	Cache hits from your own prior validations (free)
local_rejections	Rejected locally by syntax error or missing MX record (free)
valid	Contacts with validation outcome Valid
invalid	Contacts with validation outcome Invalid
greylist	Contacts with validation outcome Greylist

Returns validated contacts for your company, paginated. Supports date filtering, free-text search, and sorting. Available to all API keys — results are automatically scoped to your company. Admin keys can additionally filter by any company via company_id.

Request

GET /api/v1/contacts?start_date=2026-03-01&end_date=2026-03-31&limit=1000&offset=0
X-API-Key: <your-key>

Param	Type	Default	Description
start_date	YYYY-MM-DD	—	Filter by last_called start date
end_date	YYYY-MM-DD	—	Filter by last_called end date (inclusive)
search	string	—	Free-text search on email address, status, or domain
order_by	string	id	id, email, status, domain, mx_records, date_last_validated, last_called
order_dir	asc / desc	desc	Sort direction
offset	int	0	Number of records to skip (for pagination)
limit	int	50	Records per page — maximum 1000
company_id	int	—	Admin keys only. Ignored for standard keys.

Response

{
  "draw": 1,
  "recordsTotal": 2492784,
  "recordsFiltered": 2099431,
  "data": [
    {
      "id": 10779707,
      "email": "user@example.com",
      "status": "Valid",
      "domain": "example.com",
      "mx_records": "mx1.example.com",
      "date_last_validated": "2026-03-31 07:01:25",
      "last_called": "2026-03-31 07:01:25"
    }
  ]
}

Field	Description
recordsTotal	Total contacts stored for this company (no date filter applied)
recordsFiltered	Contacts matching the current filters
data	Array of contacts for this page
status	Valid, Invalid, or Greylist

Paginating through all contacts: increment offset by limit on each request until the returned data array is empty or shorter than limit.

Returns a CSV file once the job status is Done.

Request

GET /api/v1/jobs/42/download
X-API-Key: <your-key>

Response — text/csv

email,status
alice@example.com,Valid
bob@example.com,Invalid
charlie@example.com,Greylist

The status column contains Valid, Invalid, or Greylist.

cURL Examples

List companies

curl -s https://verify.sendability.com/api/v1/companies \
  -H "X-API-Key: YOUR_KEY"

Single email

curl -s -X POST https://verify.sendability.com/api/v1/validate/single \
  -H "X-API-Key: YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"email": "test@example.com", "company_id": 1}'

Single email — force revalidate (skip cache)

curl -s -X POST https://verify.sendability.com/api/v1/validate/single \
  -H "X-API-Key: YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"email": "test@example.com", "company_id": 1, "force_revalidate": true}'

Bulk file upload

curl -s -X POST "https://verify.sendability.com/api/v1/validate/file?company_id=1" \
  -H "X-API-Key: YOUR_KEY" \
  -F "file=@emails.csv"

Poll until done & download

# Poll status
curl -s https://verify.sendability.com/api/v1/jobs/42 \
  -H "X-API-Key: YOUR_KEY"

# Download results (once status=Done)
curl -s https://verify.sendability.com/api/v1/jobs/42/download \
  -H "X-API-Key: YOUR_KEY" -o results.csv

Billing summary for March

curl -s "https://verify.sendability.com/api/v1/reports/summary?start_date=2026-03-01&end_date=2026-03-31" \
  -H "X-API-Key: YOUR_KEY"

Retrieve all contacts for March (paginated)

# Page 1
curl -s "https://verify.sendability.com/api/v1/contacts?start_date=2026-03-01&end_date=2026-03-31&limit=1000&offset=0" \
  -H "X-API-Key: YOUR_KEY"

# Page 2
curl -s "https://verify.sendability.com/api/v1/contacts?start_date=2026-03-01&end_date=2026-03-31&limit=1000&offset=1000" \
  -H "X-API-Key: YOUR_KEY"

# Keep incrementing offset by 1000 until data array is empty

Search for a specific email

curl -s "https://verify.sendability.com/api/v1/contacts?search=user@example.com" \
  -H "X-API-Key: YOUR_KEY"