POST /v1/verify

Verify a single email address synchronously. Returns under 100ms for most requests.

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 if the email passed all critical checks.
`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.

Response examples

Response200 OK

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

Response — disposable email422 Unprocessable Entity

{
  "error": "validation_failed",
  "data": {
    "valid": false,
    "score": 3,
    "disposable": true,
    "reason": "disposable_domain",
    "latency_ms": 41
  }
}

Response — unauthorized401 Unauthorized

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

Code examples

import Mailbeam from "@mailbeam/sdk";
const mb = new Mailbeam({ apiKey: process.env.MAILBEAM_KEY });
const { valid, score, reason } = await mb.verify("user@example.com");
if (!valid || score < 60) throw new Error(reason);

Try it out

Interactive playground — coming soon

Endpoint: /v1/verify