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/validationschecks 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
{ "email": "jane@gmail.con" }{
"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
result | Meaning | What to do |
|---|---|---|
deliverable | The domain accepts mail and nothing looks risky. | Accept it. |
risky | Deliverable, 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. |
undeliverable | It 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. |
unknown | The 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.
| Check | Property | How it's decided |
|---|---|---|
syntax | The address is well-formed | Parsed against the same rules every send uses. |
dns | The domain accepts mail | The 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. |
mailbox | The mailbox exists | low 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. |
role | It reaches a function, not a person | support@, billing@, no-reply@ and similar. A role address is fine for transactional mail and never makes a result risky. |
disposable | It's a throwaway inbox | A list of known disposable domains (including their subdomains), plus mail servers that host throwaway inboxes. |
random | The local part looks machine-generated | A 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
ccorbccthat can't receive mail is removed, and the message still goes to everyone else. - When no
torecipient can receive it, nothing is sent. The message shows assuppressed, and itssuppressedevent carries{ "reason": "invalid_recipient", "detail": "domain_not_found" }(ornull_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.