API Reference

The Mailbeam REST API allows you to verify email addresses, run batch jobs, and monitor your account usage.

Base URL

All endpoints are under /v1/. Breaking changes will be introduced in new versions (/v2/, etc.).

Authentication

All requests require a Bearer token in the Authorization header:

Authorization: Bearer mb_live_xxxxxxxxxxxxxxxxxxxx

See Authentication for key types, rotation, and test mode.

Content type

Requests with a body must send Content-Type: application/json. All responses return Content-Type: application/json.

Versioning

The current API version is v1. We maintain backwards compatibility within a version. When breaking changes are necessary, we introduce a new version and deprecate the old one with at least 12 months notice.

Idempotency

The POST /v1/verify endpoint is safe to retry — it has no side effects. Calling it twice for the same email returns the same result (plus or minus timing/network variance).

For POST /v1/verify/batch, use the Idempotency-Key header to safely retry submissions without creating duplicate jobs:

Idempotency-Key: your-unique-job-id

Response envelope

All successful responses return the result directly (no envelope wrapper). Errors return:

{
  "error": "error_code",
  "message": "Human-readable description.",
  "request_id": "req_01hx9abc123"
}

Endpoints