Detection overview

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:

1. Syntax validation — RFC-aware parsing, IDNA, IANA TLD list. When syntax_validation is false, other classification fields reflect the raw input only.
2. Normalization — provider-specific canonical form in normalized.
3. Subaddressing — whether plus-tags or provider rules changed the local part.
4. Role address — shared inboxes such as admin@ or support@.
5. Public domain — freemail and consumer mailbox providers.
6. Relay domain — privacy forwarding services (SimpleLogin, Firefox Relay, Proton Pass, and similar).
7. 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

Guides by signal

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