Typo suggestions
suggested_email and suggested_domain are advisory corrections. syntax_validation can stay false. normalized still follows the submitted host.
Email typo suggestions are candidate corrections for a misspelled domain or TLD. They do not make the submitted address valid. EmailGuard returns them as suggested_email and suggested_domain on GET /api/v1/emails/detect. Show a “Did you mean …?” prompt. Do not rewrite the field silently. Do not treat a suggestion as a pass on syntax validation.
Fields
| Field | Meaning |
|---|---|
suggested_domain | Replacement host when a catalog rule matches (for example gmail.com) |
suggested_email | Full candidate mailbox, after provider rules on that suggested host |
normalized | Canonical form of the submitted address, not the suggestion |
syntax_validation | Whether the submitted addr-spec passed. Independent of the suggestion |
Omitted when empty. A missing pair means no catalog rule fired, not “the address is perfect.”
Full field list: email detection overview. API: Detect email characteristics.
How EmailGuard picks a suggestion
Rules are deterministic catalog matches, not Levenshtein distance.
- Domain typo rules rewrite a known misspelling of a provider host (
ggmail.→gmail.). - TLD typo rules rewrite a known bad suffix (
.aom→.com,.ccom→.com). - Both can chain.
test-email@bogpond.ccombecomessuggested_domainbigpond.com. suggested_emailis then normalized against the suggested domain. Gmail rules strip dots and+tags on that candidate.
Mailcheck (the library most “did you mean” posts copy) defaults to Sift3, not Levenshtein, unless you pass distanceFunction. We do not ship Mailcheck. We ship a maintained typo catalog. If a blog says “EmailGuard uses Levenshtein,” that is the Mailcheck folklore, not this API.
Syntax can stay false
Abstract’s Email Validation docs (fetched 2026-09-03) leave autocorrect empty when is_valid_format is false. Other checks still run on the original when format is valid. Kickbox returns did_you_mean next to an undeliverable result and tells you to confirm before continue.
EmailGuard still suggests when the address parses but the TLD is not in IANA. That is the case signup forms actually hit: gmail.con, ggmail.aom, hotmial.ccom.
From our tests, jane.dot+newsletter@ggmail.aom:
{
"syntax_validation": false,
"domain": "ggmail.aom",
"normalized": "jane.dot@ggmail.aom",
"subaddressing": true,
"suggested_domain": "gmail.com",
"suggested_email": "janedot@gmail.com"
}normalized followed the submitted host (plus-strip only, because ggmail.aom is not Gmail). suggested_email applied Gmail rules on gmail.com. Two different strings. One job each: dedupe what they typed vs prompt what they probably meant.
test-email@bogpond.ccom returns syntax_validation false, normalized test-email@bogpond.ccom, suggested_email test-email@bigpond.com.
What to do in the form
- Call detect on blur or submit, not on every keystroke.
- If
suggested_emailis present, show a clickable Did you mean …? confirm with that value. Kickbox’s integration guides and a long UX Stack Exchange thread agree: silent rewrite is how you send a confirmation to a third-party MX. - On confirm, replace the input and call detect again on the confirmed value. Store that 2xx, not the typo.
- If the user declines, keep
syntax_validation: falseas a hard stop when syntax failed. For a syntactically valid lookalike (gamil.comis a real registration; Kickbox still maps many of those to Gmail), decide whether you prompt or accept. Do not auto-flip corporate lookalikes. - Keep the API key on the server. The syntax checker is for humans poking one address, not for shipping your secret in the browser.
Plus tags on a correct Gmail address are not typos. See normalize plus-addressed emails at signup. subaddressing is a different flag.
What suggestions are not
- Not a validity upgrade.
syntax_validationstays whatever the submitted string earned. - Not mailbox existence. We do not SMTP-probe. A suggested
janedot@gmail.comcan still be unused. - Not a local-part spellchecker.
jame.smith@gmail.comwill not becomejames. Only domain and TLD catalog rules fire. - Not disposable detection. A suggestion can point at Gmail while the original host is garbage. Run disposable on the address you actually store.
Vendor field names
If you are migrating:
| Vendor | Suggestion field |
|---|---|
| EmailGuard | suggested_email + suggested_domain |
| Kickbox, ZeroBounce, Mailgun Validate, Mailboxlayer | did_you_mean |
| Abstract | autocorrect |
| NeverBounce | suggested_correction |
They return one string. We return the host and the fully normalized candidate separately so you can show the domain fix without guessing how Gmail rewrites the local part.
FAQ
What is an email typo suggestion?
A candidate corrected mailbox for a domain or TLD misspelling, such as gmial.com → gmail.com. In EmailGuard it is suggested_email plus suggested_domain. It is advisory.
Should I auto-correct the email field?
No. Prompt “Did you mean …?” and require a click. Silent correction can send mail to a typosquat or a rare real domain that looks like Gmail.
Does a suggestion mean the address is valid?
No. syntax_validation can be false while suggestions are present, especially on invalid TLDs.
Why is normalized different from suggested_email?
normalized is the submitted host after provider rules that apply to that host. suggested_email applies rules to the suggested host. A Gmail typo keeps dots on normalized and strips them on suggested_email.
Is this Levenshtein?
No. EmailGuard uses catalog domain_typo and tld_typo rules. Mailcheck’s default distance is Sift3.