Pending results

POST /v1/verifications runs the deterministic checks — syntax, domain, mail routing — and, where the address survives them, asks a destination about the recipient. When that evidence is not back inside the request’s budget, the answer is:

{
  "id": "5f0b6f3e-1a4c-4a1f-9d2e-8f7b3c2a1d90",
  "status": "pending",
  "retry_after_ms": 2000,
  "reason_codes": ["MX_FOUND", "SMTP_QUEUED"],
  "checks": { "syntax": "valid", "domain": "valid", "mail_routing": "valid", "smtp": "unknown" }
}

pending is not a verdict. It is the service saying the question is still open.

Retrieving the answer

curl -sS https://api.emvero.tech/v1/verifications/5f0b6f3e-1a4c-4a1f-9d2e-8f7b3c2a1d90 \
  -H "Authorization: Bearer emv_your_credential"

The same body shape comes back, with a terminal status once the evidence has arrived.

Honour retry_after_ms. It is not a formality — it is how long the service expects the outstanding work to take, and polling faster spends your rate allowance to learn nothing. Give your loop a deadline of your own, and treat expiry as unknown rather than as a failure.

There are no callbacks

Polling is the only way a late result reaches you. This is a deliberate absence rather than a missing feature: a webhook is an endpoint we would have to authenticate to, retry against, and hold results for, and every one of those is a way for somebody else’s outage to become ours.

What makes an answer late

Mostly the destination. Greylisting — a temporary refusal that means “come back later” — is the common case, and a retry is scheduled automatically. So are throttling, a slow connection, and a destination we are pacing ourselves against because it has had enough from us for now.

The reason codes on the pending response say which: SMTP_QUEUED is the ordinary one, and the vocabulary has the rest.

Pending is free

A pending response is not charged. X-Credits-Charged on it reads 0, and the charge — if there is one — is applied where the verification becomes an answer, exactly once, however many times you poll for it.

That is the honest arrangement and it is also the useful one: you are never charged twice for one question, and you are never charged for a question that was never answered. See Credits.

Retries are background work

A retry belongs to a verification that was answered pending minutes ago and that the destination itself asked us to come back for. Nobody is holding a connection open for it, so it runs at the lowest priority whatever credential it belongs to — behind every request somebody is currently waiting on, including your own. See Limits and pacing.

Identifiers of other callers

A 404 from GET /v1/verifications/{id} means there is no such verification for this credential. An identifier belonging to somebody else is reported exactly the same way as one that never existed, which is what stops the endpoint being used to discover whether other people’s verifications exist.