Skip to Content
Docs
Guides

Address validation

Check an address before you collect it — and know that every send is checked before it leaves.

Bounces cost you twice: the message never arrives, and every hard bounce counts against your sending reputation. emitd guards against them in two places.

  • On every send, automatically. Right before a message leaves, emitd drops any recipient whose address cannot possibly receive it. You don't call anything to get this.
  • At the point of collection, on request. POST /v1/validations checks one address — on your sign-up form, before you add a contact — and can suggest a fix for a typo while the person is still there to accept it.

Validate an address

POST /v1/validations
{ "email": "jane@gmail.con" }
200 OK
{
  "email": "jane@gmail.con",
  "result": "undeliverable",
  "reason": "domain_not_found",
  "did_you_mean": "jane@gmail.com",
  "checks": {
    "syntax": "high",
    "dns": "low",
    "mailbox": "medium",
    "role": "low",
    "disposable": "low",
    "random": "low"
  }
}

Any key that can send can validate. A malformed address is not an error — it comes back 200 with result: "undeliverable" and reason: "invalid_syntax", so your form can treat every answer the same way. Full schema: Validation API.

result

resultMeaningWhat to do
deliverableThe domain accepts mail and nothing looks risky.Accept it.
riskyDeliverable, but the domain is disposable, the address looks machine-generated, or the domain has no MX record.Accept with care — or ask for another address.
undeliverableIt will bounce: bad syntax, no such domain, the domain refuses all mail, no mail server, or it has hard-bounced before.Don't send. Offer did_you_mean if present.
unknownThe domain's DNS couldn't be read just now.Accept it, or retry later. Never treat it as invalid.

reason says why a result isn't deliverable: invalid_syntax, domain_not_found, null_mx, no_mail_server, previously_bounced, dns_unavailable, disposable, random_input or no_mx_record. It is null for a deliverable address.

checks

Each check reports how strongly its property holds — high, medium or low. high on disposable means very likely disposable: the scale measures the property, not how good it is.

CheckPropertyHow it's decided
syntaxThe address is well-formedParsed against the same rules every send uses.
dnsThe domain accepts mailThe domain's MX records, falling back to A/AAAA as mail servers do. A missing domain, a null MX or no server at all is low.
mailboxThe mailbox existslow when the address has hard-bounced before — on your own suppression list or emitd's cross-account blocklist (never another account's list). Otherwise medium: emitd never probes mail servers, because probing gets senders blocklisted.
roleIt reaches a function, not a personsupport@, billing@, no-reply@ and similar. A role address is fine for transactional mail and never makes a result risky.
disposableIt's a throwaway inboxA list of known disposable domains (including their subdomains), plus mail servers that host throwaway inboxes.
randomThe local part looks machine-generatedA conservative heuristic — ordinary names stay low.

did_you_mean

When the domain looks like a slip — gmial.com, hotmial.com, gmail.con, acme.con — did_you_mean carries the corrected address. Show it to the person ("Did you mean jane@gmail.com?") rather than silently changing what they typed. Real regional domains such as hotmail.ca are never "corrected".

Limits

Each workspace can run 1,000 validations per rolling 24 hours, shared by all its keys. Past that, the call returns 429 with { "error": "validation_limit_reached" }. A call that fails with 503 (validation_unavailable) is not counted.

Protection on every send

You don't need the API for this part. After a send is accepted, and just before it is handed off for delivery, emitd checks every recipient's domain. A recipient that cannot receive mail — invalid address, no such domain, a domain that refuses all mail, or no mail server — is dropped:

  • A cc or bcc that can't receive mail is removed, and the message still goes to everyone else.
  • When no to recipient can receive it, nothing is sent. The message shows as suppressed, and its suppressed event carries { "reason": "invalid_recipient", "detail": "domain_not_found" } (or null_mx, no_mail_server, invalid_syntax).

Only certainties are acted on. A risky or unreadable address is always sent to — emitd will not turn away real mail on a guess, or because DNS was slow for a moment.

A live domain can still have a dead mailbox (info@ at a company that closed its account, say). Those are caught one step later: each recipient's mailbox is validated as the message is delivered, and one that fails is stopped there. It shows up the same way — a suppressed event with reason: "invalid_recipient" — and the address joins your suppression list, so later sends skip it entirely. A recipient stopped this way is never counted as a bounce against you.

Suppressed ≠ error

As with the suppression list, a recipient dropped this way is a normal outcome, not a 4xx.

On this page