Check one address

POST/api/v1/verifications/check
Requires anorganization API keywith the scopeverification:write

Checks one address and answers in the same call when it can — a mailbox we have not seen before can take a few seconds. Use it at sign-up, before an address goes into your database.

Costs 10 send credits, charged only when there is an answer. A pending result costs nothing; ask again a little later.

Parameters

NameInTypeDescription
Idempotency-KeyheaderstringSend a unique value — a UUID is ideal — to make this request safe to retry. If we have already answered a request with the same key and the same body, you get that exact response back with `Idempotent-Replayed: true` and nothing is sent a second time. Reusing a key with a DIFFERENT body is a 409, because answering the first response to a second message would silently swallow it. Keys are scoped to your organization and honoured for 24 hours. A 5xx does not record a key: we cannot say whether the message left, so your retry genuinely retries. Omit the header and nothing changes.

Request body

  • emailstringrequired

Request

POST/api/v1/verifications/check
curl -X POST 'https://app.mailyte.com/api/v1/verifications/check' \
  -H 'Authorization: Bearer mk_live_YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "email": "<string>"
  }'
The key names its own organization, so no X-Organization-ID header is needed.

Response

The answer, or `pending` if it is still being checked.

  • dataobject
    • objectstringverification_result
    • emailstring
    • resultstringvalid | invalid | risky | unknown | pending

      Mail to `invalid` is refused. `risky` and `unknown` are sent as normal. `pending`: still being checked.

    • reasonstringmailbox_exists | mailbox_does_not_exist | domain_cannot_receive_mail | misspelt_domain | invalid_syntax | disposable_address | accepts_all_addresses | role_address | provider_does_not_confirm | could_not_confirm | checking
    • flagsarray<string>

      `role`: info@, sales@ and the like. `disposable`: a throwaway inbox (marketing to it is not sent). `catch_all`: the domain accepts any address.

Returned inside the standard envelope.

Errors

StatusWhen
401The API key is missing, unknown, revoked or expired. All four answer identically, on purpose: distinguishing them would confirm which keys exist.
403The key is valid but may not do this: it lacks the required scope, its IP allowlist does not include you, or this endpoint does not accept API keys.
404No such resource in this organization.
422The request was understood but the values were not acceptable.
429Too many requests, or the organization has spent its sending allowance. `Retry-After` says how long to wait.

Every status, with what causes it and what to do, is on the error reference.