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.
The response is built from six checks that run in sequence, each of which can be inspected on its own:
| Field | What it means |
|---|---|
checks.format | Syntax test against a local-part@domain pattern |
checks.mx_exists + mx_records | Domain has mail servers; up to five MX hosts with priorities |
checks.smtp_verified + smtp_detail | Result of a live SMTP RCPT TO handshake with the highest-priority MX |
checks.disposable | Matches a built-in list of roughly 110 throwaway/relay domains |
checks.role_account | Local part is a role prefix such as admin, support, billing, no-reply (31 known prefixes) |
checks.typo_suggestion | Near-miss domain for Gmail, Hotmail, Yahoo, Outlook, iCloud, or AOL |
valid + reason | Overall verdict and the human-readable reason when it fails |
mailbox | valid, role, risky, or invalid |
confidence | high, medium, or low — how much the signals agree |
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
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:
valid is false with a reason, and typo_suggestion carries a corrected address you can offer the user.mx_exists is false and the reason says the domain has no mail servers. This is your cheapest, most reliable rejection.smtp_verified is false and smtp_detail contains the server's numeric response, for example SMTP server rejected the recipient (code 550).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.
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.
Knowing the mechanics tells you when to trust a result:
+ or . is compared against 31 known role prefixes (admin, support, sales, noreply, postmaster, and friends). A role hit does not by itself make an address invalid; it sets mailbox to role so you can route it differently.Disposable email domain.typo_suggestion returns the corrected address (ada@gmail.com from ada@gmial.com), which is exactly what you want to show a user mid-signup.HELO, MAIL FROM, and RCPT TO, and reads the reply. An 250 acceptance sets smtp_verified: true. Explicit rejections such as 550, 551, 552, 553, 450, or 452 fail the check and are reported in smtp_detail. The whole handshake is bounded by an 8-second timeout.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.
Pricing for this endpoint is deliberately boring:
| Identity | Free checks per day | After the free quota |
|---|---|---|
| Anonymous (per IP) | 3 | Sign in and attach a key, then 1 flexible credit per check |
| Free account or free agent key | 3 | 1 flexible credit per check |
| Premium plans (Pro, Builder, Teams) | 50 | Plan 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.
confidence: low as a review item, not a ban.free_remaining in the response.smtp_detail instead of probing your network.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.
Run the same checks from the Agent Intelligence panel, or call POST /api/agent/email/verify from your own stack.
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.