Your first email detection check

This walkthrough takes you from a dashboard key to a successful detect response. Deep field semantics live in the email detection overview.

1. Create an API key

1. Select the team that should own the integration.
2. Open Team → API keys (or follow Creating API keys).
3. Create a key that includes the email:detect scope.
4. Copy the secret immediately — it is shown only once.

Scope reference: API key scopes.

2. Call the detect endpoint

curl -sS -H "Authorization: Bearer YOUR_API_KEY" \
  "https://api.emailguard.co/api/v1/emails/detect?email=user%40example.com"

Use your real API host if it differs. Prefer an official SDK client in production.

3. Read the response

A 2xx body always includes confidence and evidence, plus the usual syntax, normalized form, and flags (disposable, role, public domain, relay). Cached DNS snapshots may add mx_present, wildcard_dns, and infra_cluster_match. Those are classification flags, not mailbox probes.

If your team configured overlay rules, you may also see policy_action and suggested_action.

Full schema: Detect email characteristics. Signup policy: Confidence, evidence, and fail-open.

4. Handle limits and outages

• 429 — back off using Retry-After. See API rate limiting.
• Timeout / 5xx — fail open on ordinary signup. Create the account, log the miss, recheck later. Set your HTTP client timeout to at least 2 seconds so live DNS can finish.
• 2xx and disposable: true — block. That is a verdict, not an outage.
• Monthly quota — successful detects count toward the team's plan when billing is enabled. Check Billing usage.

Next

• Signup patterns: Block disposable emails at signup
• Outages vs verdicts: Confidence, evidence, and fail-open
• Auth libraries: Block disposable emails in Better Auth and Clerk
• Supabase Auth: Block disposable emails in Supabase
• Dashboard vs API: Integrating from the dashboard