API documentation

Version 1 · updated 18 September 2026

Private beta. Endpoints and field names are stable. Rate limits may still change. Write to hello@zyloriso.com for a key.

On this page

Base URL and authentication
Verify one address
Status values
Reason codes
Caching and reuse
Bulk verification
Rate limits
Errors
Data handling

Base URL and authentication

https://api.zyloriso.com/v1
Authorization: Bearer YOUR_API_KEY

Every response is JSON. Timestamps are UTC in ISO 8601. The key goes in the header, never in the query string.

Verify one address

GET /v1/verify?email=jane@example.com

{
  "email": "jane@example.com",
  "status": "valid",
  "score": 96,
  "reason": "mailbox_exists",
  "domain": { "name": "example.com", "mx": "mail.example.com", "catch_all": false },
  "flags": { "disposable": false, "role": false, "free": false, "typo_suggestion": null },
  "checked_at": "2026-09-18T10:42:11Z",
  "credits_used": 1
}

Status values

The status field answers one question: can mail be delivered to this address? Everything else is reported through flags, so a role account or a free-provider address keeps its real deliverability instead of being replaced by a label.

status	Meaning	What to do
`valid`	The mail server confirmed the mailbox exists.	Keep.
`invalid`	Syntax error, dead domain, no MX, or the server rejected the recipient. Also covers a mailbox the provider reports as disabled.	Remove.
`catch_all`	The domain accepts every recipient, so existence cannot be confirmed. Also covers a real mailbox that is currently over quota.	Send cautiously and watch bounces.
`disposable`	Temporary mailbox provider.	Remove, or block at signup.
`unknown`	The remote server gave no usable answer after retries.	Re-check later; free within 24 hours.

On accept-all domains and Yahoo. We test every domain for accept-all behaviour rather than inferring it from the mail provider. Company domains on Google Workspace and Microsoft 365 are frequently accept-all, and Yahoo and AOL accept every recipient during busy periods then bounce afterwards. Those addresses come back as catch_all, never as valid, because a guess should not be reported as a confirmation.

Reason codes

reason	Description
`mailbox_exists`	The server confirmed the recipient.
`mailbox_not_found`	The server rejected the recipient with a 5xx user-unknown reply.
`mailbox_inactive`	The mailbox exists on paper but the provider has disabled or abandoned it. Reported as `invalid`.
`mailbox_full`	A real mailbox that is over quota and cannot take mail right now. Reported as `catch_all`.
`invalid_syntax`	The address is not RFC 5322 compliant.
`no_mx`	The domain has no MX or A record, or publishes a Null-MX.
`domain_not_found`	The domain does not resolve.
`catch_all_domain`	The domain accepts all recipients.
`disposable_domain`	The domain is on the disposable-provider list.
`greylisted`, `timeout`, `rate_limited`	Temporary conditions, retried automatically before anything is reported as unknown.

Caching and reuse

A result carrying "cached": true, or a reason ending in (cached), was reused from an earlier check. How long a result stays reusable depends on how fast that kind of answer goes stale.

Result	Reused for
`valid` and `catch_all`	7 days
Domain with no mail server	14 days
Malformed, non-existent and disposable	30 days
`unknown`	Never stored, always re-checked

Free-provider mailboxes are held for a shorter window than the table above, because a Gmail or Outlook mailbox changes hands more often than a company one.

Bulk verification

Upload a file, poll for progress, download the results. Files up to 5,000,000 rows.

POST /v1/bulk            multipart/form-data: file=list.csv
GET  /v1/bulk/{job_id}   -> { "status": "processing", "progress": 0.42, ... }
GET  /v1/bulk/{job_id}/download?format=csv|json

Pass an optional webhook_url on upload to get a POST when the job finishes. A download is refused while any row is still pending, so a partial file can never be mistaken for a finished one.

Rate limits

Plan	Real-time requests	Bulk throughput
Starter	10 per second	Shared queue
Growth	50 per second	Priority queue
Scale and Enterprise	200 per second	Dedicated capacity

Going over a limit returns HTTP 429 with a Retry-After header. Limits are counted per API key.

Errors

HTTP	code	Meaning
400	`bad_request`	A parameter is missing or malformed.
401	`unauthorized`	The API key is invalid.
402	`insufficient_credits`	Top up to continue.
429	`rate_limited`	Slow down; see Retry-After.
500	`internal_error`	Retry with exponential backoff.

Data handling

Addresses submitted through the API are kept only as long as needed to return the result, plus 30 days of job history, and are then deleted. See the privacy policy and the terms of service. A data-processing agreement under Article 28 GDPR is available on request.