Agent decision guide

When building an AI agent that verifies email addresses, the raw API response gives you the data, but your agent needs to know what to do with it.

This guide defines the standard decision matrix for agents consuming the truval.dev API.

Decision order. Follow this sequence so UX and risk handling stay consistent — the evaluateEmail example below uses the same order: suggestion first (offer a correction before rejecting); disposable (hard reject regardless of other signals); invalid / undeliverable (definitive rejects — evaluate these before role so you do not flag a generic inbox when the address is already bad); role (policy flag — not a hard reject like disposable); catch-all and unknown with MX when SMTP is inconclusive on a real domain (do not treat like junk in the < 0.5 band); smtp_blocked with sufficient confidence so major-provider probes are not misread as invalid; then confidence bands for everything else.

Status and flags first, then confidence

The confidence field is an ordinal summary (how decisive the check was under truval.dev’s rules). It is not a calibrated probability that the mailbox exists. Always combine it with status, failed_check, mx_found, and smtp_blocked.

See also: confidence ladder on the Email verify page.

Confidence thresholds

After handling typos, disposables, invalid / undeliverable, role (if your product branches on it), catch-all, and smtp_blocked, use bands below for remaining cases:

Confidence	Meaning	Agent Action
>= 0.9	SMTP deliverable (status: deliverable).	Accept and proceed.
0.7 - 0.9	Usually smtp_blocked with domain/MX OK (confidence ~0.75).	Accept with low risk. Do not treat valid: false as failure when smtp_blocked is true.
0.5 - 0.7	Often catch-all (~0.65) or inconclusive SMTP on a real domain (~0.50: unknown, mx_found, not smtp_blocked).1	Ask user to confirm or apply extra checks — not the same as “invalid.”
< 0.5	Typically undeliverable (~0.02) or invalid path (0.0).	Reject or ask for a different email — but only after you have not matched an inconclusive-unknown case above.

Handling specific flags

In addition to confidence, your agent must handle specific situational flags returned by the API:

1. Disposable addresses

disposable: true

• Meaning: The email belongs to a throwaway or temporary email service (like Mailinator).
• Agent Action: Reject. Do not allow temporary emails for account creation or persistent communications.

2. Role addresses

role: true

• Meaning: The email is a generic role inbox (e.g., admin@, support@, info@, sales@), rather than a specific person.
• Agent Action: Flag. Depending on your use case, you may want to proceed, but if your workflow requires communicating with a specific individual, ask the user for a direct email address instead.

3. Typo suggestions

suggestion !== null

• Meaning: The API detected a likely typo (e.g., gnail.com instead of gmail.com) and provided a correction in the suggestion field.
• Agent Action: Offer correction to user. Say: “Did you mean [suggestion]?” and wait for confirmation before proceeding.

4. SMTP Blocked

smtp_blocked: true

• Meaning: The provider (Gmail, Outlook, Yahoo, iCloud) blocks all third-party SMTP probing.
• Agent Action: Use the confidence score, not the valid field. Do not treat valid: false as a hard failure. A score of 0.75 for a Gmail address with smtp_blocked: true is an expected result and should be accepted (falls in the 0.7-0.9 bucket).

5. Catch-all domains

catch_all: true or status: "catch_all"

• Meaning: The receiving server accepts arbitrary recipient addresses on that domain. This does not prove the specific mailbox exists.
• Agent Action: Treat with caution even when valid: true. Catch-all responses are intentionally scored lower (confidence: 0.65) and should be handled as low-certainty results (ask user to confirm, require double opt-in, or apply additional risk checks).

6. Unknown with MX but SMTP inconclusive

status === "unknown" and mx_found === true and smtp_blocked === false

• Meaning: The domain is not on the major-provider block list and has MX records, but the SMTP conversation did not yield a clear deliverable / undeliverable / catch-all outcome (common for org and Microsoft 365–hosted domains). Typical confidence is 0.50.
• Agent Action: Do not auto-reject as invalid. Treat like low certainty: confirm with the user, allow with a warning, or use a second factor — same band as catch-all caution, different reason.

Example decision logic

function evaluateEmail(result) {
  if (result.suggestion) {
    return { action: "ask_correction", suggestion: result.suggestion };
  }
  if (result.disposable) {
    return { action: "reject", reason: "disposable_email_not_allowed" };
  }
  if (result.status === "invalid") {
    return { action: "reject", reason: "invalid_email" };
  }
  if (result.status === "undeliverable") {
    return { action: "reject", reason: "mailbox_not_found" };
  }
  if (result.role) {
    return { action: "flag_role_address", reason: "generic_inbox_not_personal" };
  }
  if (result.catch_all || result.status === "catch_all") {
    return { action: "ask_user_confirmation", reason: "catch_all_mailbox_uncertain" };
  }
  if (result.status === "unknown" && result.mx_found && !result.smtp_blocked) {
    return { action: "ask_user_confirmation", reason: "smtp_inconclusive_org_domain" };
  }
  if (result.smtp_blocked && result.confidence >= 0.7) {
    return { action: "proceed_with_warning", reason: "provider_blocks_smtp_probe" };
  }
  if (result.confidence >= 0.9) {
    return { action: "proceed" };
  }
  if (result.confidence >= 0.7) {
    return { action: "proceed_with_warning" };
  }
  if (result.confidence >= 0.5) {
    return { action: "ask_user_confirmation", reason: "low_certainty" };
  }
  return { action: "reject", reason: "low_confidence_score" };
}

Footnotes

1. Includes org domains and Microsoft 365 — see Unknown with MX but SMTP inconclusive below. ↩