← Back to blog

Email Verification API for Agents: MX, SMTP, Disposable, and Typo Checks

September 19, 2026 · Eric · 7 min read

Bad email addresses leak into systems the same way every time: a signup form where someone typed gmial.com, a scraped list full of throwaway inboxes, a CRM import where every row is info@ and nobody reads any of them. Each bad address costs you a bounce, a wasted send, and a small dent in sender reputation.

Catching those problems normally means gluing together a DNS resolver, an SMTP client, a disposable-domain list, and a table of common typos — then keeping all of it running. Agent Media Tools exposes that work as one endpoint: POST /api/agent/email/verify. Send one address as JSON, get back six independent signals plus a plain-language verdict.

It works from curl with no account at all, and with an mt_ agent API key when you need volume or an audit trail.

What one request returns

The response is built from six checks that run in sequence, each of which can be inspected on its own:

FieldWhat it means
checks.formatSyntax test against a local-part@domain pattern
checks.mx_exists + mx_recordsDomain has mail servers; up to five MX hosts with priorities
checks.smtp_verified + smtp_detailResult of a live SMTP RCPT TO handshake with the highest-priority MX
checks.disposableMatches a built-in list of roughly 110 throwaway/relay domains
checks.role_accountLocal part is a role prefix such as admin, support, billing, no-reply (31 known prefixes)
checks.typo_suggestionNear-miss domain for Gmail, Hotmail, Yahoo, Outlook, iCloud, or AOL
valid + reasonOverall verdict and the human-readable reason when it fails
mailboxvalid, role, risky, or invalid
confidencehigh, medium, or low — how much the signals agree

Step 1 — call it with curl

Anonymous — 3 free checks per day

No header, no key, no signup. Send the address as JSON:

curl -s -X POST https://agentmediatools.com/api/agent/email/verify \
  -H "Content-Type: application/json" \
  -d '{"email":"ada@example.com"}' | jq .

The email field is the only required input. With an agent key, add a Bearer header so the request is attributed to your key instead of your IP:

export AMT_KEY="mt_your_agent_key"

curl -s -X POST https://agentmediatools.com/api/agent/email/verify \
  -H "Authorization: Bearer $AMT_KEY" \
  -H "Content-Type: application/json" \
  -d '{"email":"ada@example.com"}' | jq .verification

Step 2 — read the response

A deliverable address on a well-behaved mail server looks like this (abbreviated):

{
  "success": true,
  "verification": {
    "email": "ada@example.com",
    "valid": true,
    "reason": null,
    "checks": {
      "format": true,
      "mx_exists": true,
      "smtp_verified": true,
      "disposable": false,
      "role_account": false,
      "typo_suggestion": null
    },
    "mailbox": "valid",
    "confidence": "high",
    "mx_records": [
      { "exchange": "mx1.example.com", "priority": 10 }
    ],
    "smtp_detail": "SMTP server accepted the recipient"
  },
  "billing": {
    "tool": "email-verify",
    "free": true,
    "free_used": 1,
    "free_daily_limit": 3,
    "free_remaining": 2,
    "credit_cost_if_over": 1,
    "plan": "free"
  }
}

Two things are worth pointing out in that payload. First, everything about the address itself lives under verification, while billing is a separate object you can log for cost attribution. Second, free_remaining lets a caller stop before it starts spending credits — useful in a nightly batch that imports a few thousand rows from a spreadsheet.

The three outcomes you will actually branch on:

It returns immediately with checks.format: false and the reason Invalid email format. Because that rejection happens before the check is billed, a malformed string does not consume one of your three free verification checks for the day — though an anonymous request still counts against the shared site-wide call pool described below, since the HTTP call itself succeeded.

Step 3 — guard a signup route in Python

Standard library plus requests. This wrapper treats the API as one signal in a decision, not as a hard gate, and it backs off cleanly when the free quota for the day is exhausted:

import os
import requests

API = "https://agentmediatools.com/api/agent/email/verify"
KEY = os.environ.get("AMT_KEY")  # optional: mt_ agent key


def verify_email(address: str) -> dict:
    """Return {'verdict', 'reason', 'suggestion', 'billing'} for one address."""
    headers = {"Content-Type": "application/json"}
    if KEY:
        headers["Authorization"] = f"Bearer {KEY}"

    resp = requests.post(API, json={"email": address}, headers=headers, timeout=30)
    data = resp.json()

    if resp.status_code == 402:
        # Free daily checks used up and no credits left for this identity.
        return {"verdict": "unknown", "reason": data.get("error"),
                "suggestion": None, "billing": data.get("billing")}

    v = data["verification"]
    if v["valid"] and v.get("mailbox") != "role":
        verdict = "accept"
    elif v["checks"].get("typo_suggestion"):
        verdict = "suggest_fix"
    elif v.get("mailbox") == "role":
        verdict = "accept_low_priority"
    else:
        verdict = "reject" if v.get("confidence") != "low" else "review"

    return {"verdict": verdict, "reason": v.get("reason"),
            "suggestion": v["checks"].get("typo_suggestion"),
            "billing": data.get("billing")}


if __name__ == "__main__":
    for addr in ["ada@example.com", "ada@gmial.com"]:
        print(addr, verify_email(addr))

Notice the review branch: low-confidence rejections are routed to a human queue instead of being silently dropped. That distinction matters more than the raw boolean, and the next section explains why.

What each check actually does

Knowing the mechanics tells you when to trust a result:

One behavior is worth internalizing before you automate anything on top of smtp_verified: when a mail server answers with something ambiguous — typically greylisting or a tarpit — the endpoint treats the mailbox as likely deliverable rather than inventing a rejection. Combined with the confidence field, that keeps ambiguous infrastructure from quietly nuking valid customers.

Free checks, credits, and what a 402 looks like

Pricing for this endpoint is deliberately boring:

IdentityFree checks per dayAfter the free quota
Anonymous (per IP)3Sign in and attach a key, then 1 flexible credit per check
Free account or free agent key31 flexible credit per check
Premium plans (Pro, Builder, Teams)50Plan credits, then purchased credits

When the free quota is gone and there is nothing to spend, you get HTTP 402 with a message and a billing object rather than a silent failure:

{
  "success": false,
  "error": "Free daily limit for email-verify reached (3/day). Log in, create an API key, and buy credits to continue.",
  "billing": {
    "tool": "email-verify",
    "free_daily_limit": 3,
    "credit_cost": 1,
    "buy_credits": "https://agentmediatools.com/pricing"
  }
}

Two separate budgets are at play here, and conflating them causes confusing 429s. Anonymous callers share a site-wide pool of 10 free tool calls per day per IP; a free logged-in account raises that to 25. The three free email checks are the endpoint's own daily allotment on top of that. Practical rule: use a key for anything automated, and pass the key in a header rather than a query string so it never lands in a proxy log.

Boundaries worth knowing

Rolling your own versus using the endpoint

Self-hosting is genuinely viable: dnspython plus smtplib gets you MX and RCPT TO in about 40 lines, and disposable-domain lists are published freely. What you then own is the maintenance — chasing new throwaway providers, tuning timeouts so a slow MX does not stall your signup thread, handling greylisting sanely, and adding an SSRF guard so a crafted domain cannot point your SMTP client at internal infrastructure.

The hosted endpoint makes sense when email checks are a small part of a bigger workflow, when you want the typo map and disposable list maintained for you, or when a language without a good SMTP library is doing the calling. If you are verifying millions of addresses and already run mail infrastructure, self-hosting will be cheaper — that is a fair trade, and the tool page is honest about which signals it returns.

Verify an address in the browser

Run the same checks from the Agent Intelligence panel, or call POST /api/agent/email/verify from your own stack.

Open the toolbox

More reading: the DNS, SSL, and email security guide covers the domain-level records behind a working mailbox (SPF, DKIM, DMARC, MX), and the Email Verification API page documents the endpoint fields and example responses.