What is the base URL of the Mailbeam API?

https://api.mailbeam.dev, with every endpoint under the /v1/ path prefix. Requests carrying a body must send Content-Type: application/json, and all responses return JSON.

How are Mailbeam API requests authenticated?

With a Bearer token in the Authorization header, in the form: Authorization: Bearer mb_live_xxxxxxxxxxxxxxxxxxxx. There is no other authentication scheme, and keys are rotated from the dashboard.

What does a Mailbeam API error look like?

Successful responses return the result directly with no envelope. Errors return a JSON object with three fields: error (a stable machine-readable code), message (a human-readable description) and request_id, which is what support needs to trace a single call.

Which Mailbeam endpoints are safe to retry?

POST /v1/verify is safe to retry because it has no side effects — the same address returns the same result. POST /v1/verify/batch creates a job, so retries must carry an Idempotency-Key header to avoid submitting the same job twice.

The Mailbeam REST API lives at https://api.mailbeam.dev with every endpoint under /v1/. Requests authenticate with a Bearer token, send and receive JSON, and return the result directly with no envelope — errors are the only wrapped responses, carrying an error code, a message and a request_id.

Base URL: https://api.mailbeam.dev/v1/
Auth header: Authorization: Bearer mb_live_…
Content type: application/json
Error fields: error · message · request_id

API Reference

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

Base URL

https://api.mailbeam.dev

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

Method	Path	Description
`POST`	`/v1/verify`	Verify a single email
`POST`	`/v1/verify/batch`	Submit a batch of emails
`GET`	`/v1/jobs/:id`	Poll a batch job status
`GET`	`/v1/account/usage`	Get current quota usage

Frequently asked questions

Answers checked against the API contract on 2026-08-10.