Detection overview
Every field returned by GET /api/v1/emails/detect, how checks run in order, and links to deep dives on each signal.
EmailGuard analyzes a single address with GET /api/v1/emails/detect. One request returns syntax validation, a normalized mailbox form, and boolean flags for subaddressing, role addresses, consumer domains, privacy relays, and disposable domains.
Your API key needs the email:detect scope. See API key scopes.
Request and response shape
curl -sS \
-H "Authorization: Bearer YOUR_KEY" \
"https://emailguard.co/api/v1/emails/detect?email=user%2Btag%40gmail.com"Example response (fields abbreviated):
{
"code": "OK",
"data": {
"email": "[email protected]",
"syntax_validation": true,
"normalized": "[email protected]",
"subaddressing": true,
"role_address": false,
"public_domain": true,
"relay_domain": false,
"relay_provider": null,
"disposable": false,
"disposable_provider": null,
"domain": "gmail.com",
"detection_source": "precomputed"
},
"message": "ok"
}Full schema: Detect email characteristics.
How checks run
Checks are ordered so later signals only run when syntax passes:
- Syntax validation — RFC-aware parsing, IDNA, IANA TLD list. When
syntax_validationisfalse, other classification fields reflect the raw input only. - Normalization — provider-specific canonical form in
normalized. - Subaddressing — whether plus-tags or provider rules changed the local part.
- Role address — shared inboxes such as
admin@orsupport@. - Public domain — freemail and consumer mailbox providers.
- Relay domain — privacy forwarding services (SimpleLogin, Firefox Relay, Proton Pass, and similar).
- Disposable domain — throwaway inbox providers via curated intelligence, infrastructure fingerprinting, and live DNS when needed.
detection_source is precomputed when classification used EmailGuard's maintained data, or live_dns when a live MX lookup contributed to the disposable result.
Field reference
| Field | Type | Meaning |
|---|---|---|
email | string | Trimmed input you sent |
syntax_validation | boolean | Address passes RFC-aware syntax checks |
normalized | string | Canonical mailbox for deduplication |
subaddressing | boolean | Normalization removed a tag, dot alias, or similar |
role_address | boolean | Local part matches a role prefix (admin, support, …) |
public_domain | boolean | Domain is a known consumer/freemail provider |
relay_domain | boolean | Domain or MX matches a privacy relay provider |
relay_provider | string | null | Provider slug when relay_domain is true |
disposable | boolean | Domain is classified as disposable |
disposable_provider | string | null | Source label when known |
domain | string | Lowercase ASCII domain after IDNA conversion |
detection_source | string | precomputed or live_dns |
Guides by signal
| Topic | Article |
|---|---|
| Syntax, IDNA, TLD | Email valid syntax |
| Deduplication | Email normalization |
| Plus addressing | Subaddressing |
| Shared inboxes | Role-based email addresses |
| Gmail, Outlook, etc. | Public email domains |
| Forwarding aliases | Privacy relay detection |
| Throwaway inboxes | Disposable email detection |
Related docs
- API rate limiting — per-minute limits and quota headers
- Creating API keys — issue a key with
email:detect - Features — product summary of validation depth