POST /v1/verify

Verify a single email address synchronously.

An address that fails the checks is still a successful request: you get200with valid: falseand a reason. The 4xx responses below are about the request itself.

POSThttps://api.mailbeam.dev/v1/verify

Core verification endpoint. Returns verdict, quality score, and per-check breakdown.

Request body

Parameters

Name	Type	Required	Description
`email`	string	required	Email to verify. RFC 5321 format, max 254 chars.
`timeout_ms`	integer	optional (default: 3000)	SMTP probe timeout in ms. Range: 100–5000.
`include_checks`	boolean	optional (default: true)	Include per-check breakdown in response.

Response schema

Response fields

Name	Type	Required	Description
`valid`	boolean	required	true only when the mailbox was positively confirmed.
`status`	"deliverable" \| "undeliverable" \| "risky" \| "unknown"	required	Verdict. 'unknown' means we could not find out — not that the address is bad.
`score`	integer (0–100)	required	Quality score. Recommend accepting >= 60.
`disposable`	boolean	required	true if from a known temporary provider.
`catchAll`	boolean	required	true if the domain accepts all addresses.
`mx`	boolean	required	true if domain has valid, reachable MX records.
`reason`	string \| null	required	null when valid. Machine-readable reason otherwise.
`latency_ms`	integer	required	Server-side processing time in ms.
`checks`	object	required	Per-check breakdown: syntax, mx, smtp, disposable, roleAddress, freeProvider, catchAll.
`request_id`	string	required	Identifier for this request. Quote it in support tickets.

Response examples

Response200 OK

{
  "valid": true,
  "status": "deliverable",
  "score": 94,
  "disposable": false,
  "catchAll": false,
  "mx": true,
  "reason": null,
  "latency_ms": 82,
  "request_id": "req_9f2c1ab47d3e5081c6b2a904"
}

Response — address rejected by the checks200 OK

{
  "valid": false,
  "status": "undeliverable",
  "score": 10,
  "disposable": true,
  "catchAll": false,
  "mx": false,
  "reason": "disposable_domain",
  "latency_ms": 41,
  "request_id": "req_4c81f0a29b6d7e35a0c128ff"
}

Response — malformed request422 Unprocessable Entity

{
  "error": "invalid_email_format",
  "message": "The email address is not RFC 5322 compliant.",
  "request_id": "req_01hx9abc123"
}

Response — unauthorized401 Unauthorized

{
  "error": "invalid_api_key",
  "message": "The API key is invalid or revoked.",
  "request_id": "req_01hx9abc123"
}

Code examples

const response = await fetch("https://api.mailbeam.dev/v1/verify", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.MAILBEAM_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ email: "user@example.com" }),
});

const { valid, score, reason } = await response.json();
if (!valid || score < 60) throw new Error(reason);

Try it out

Interactive playground — coming soon

Endpoint: /v1/verify