Private betaMailbeam is in private beta — the public API isn't live yet.Join the waitlist

Mailbeam·Docs
Get started

Quickstart

This guide takes you from zero to your first verified email in under 5 minutes.

Prerequisites

Step 1 — Get your API key

After signing up, your first API key is created automatically. Copy it from the dashboard:

export MAILBEAM_KEY="mb_live_xxxxxxxxxxxxxxxxxxxx"

Keep your API key secret. Never commit it to version control. Use environment variables or a secrets manager.

Step 2 — Make your first request

Send a POST request to /v1/verify with the email address you want to check:

curl -X POST https://api.mailbeam.dev/v1/verify \
  -H "Authorization: Bearer $MAILBEAM_KEY" \
  -H "Content-Type: application/json" \
  -d '{"email": "user@example.com"}'

Step 3 — Read the response

A successful response looks like this:

{
  "valid": true,
  "score": 94,
  "disposable": false,
  "catchAll": false,
  "mx": true,
  "reason": null,
  "checks": {
    "syntax": true,
    "mx": true,
    "smtp": true,
    "disposable": false,
    "roleAddress": false,
    "freeProvider": false
  },
  "latency_ms": 82
}

The key fields to check in your signup flow:

  • valid — true if the email passed all critical checks
  • score — 0–100 quality score; set your own threshold (we recommend ≥ 60 for most use cases)
  • reason — null if valid, or a machine-readable string explaining why the email failed

Step 4 — Wrap the call

There is no SDK to install. Mailbeam is one HTTP endpoint, so a small wrapper in your own codebase does the job and leaves you nothing to upgrade. Official SDKs are on the roadmap — see SDKs.

// lib/mailbeam.js
const ENDPOINT = "https://api.mailbeam.dev/v1/verify";

export async function verifyEmail(email, { timeoutMs = 3000 } = {}) {
  const response = await fetch(ENDPOINT, {
    method: "POST",
    headers: {
      Authorization: `Bearer ${process.env.MAILBEAM_KEY}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ email }),
    signal: AbortSignal.timeout(timeoutMs),
  });

  if (!response.ok) {
    const { error, message } = await response.json();
    throw Object.assign(new Error(message), { code: error, status: response.status });
  }

  return response.json();
}

Step 5 — Integrate into your signup

A complete signup handler for Node.js / Express:

import { verifyEmail } from "./lib/mailbeam.js";

app.post("/api/signup", async (req, res) => {
  const { email, password } = req.body;

  let result;
  try {
    result = await verifyEmail(email);
  } catch (error) {
    // Never block a signup because we were slow or down. Decide deliberately
    // whether an unavailable check means "let them in" or "make them wait" —
    // for most products it is the former.
    console.error("mailbeam unavailable", error);
    result = { valid: true, score: 100, reason: null };
  }

  if (!result.valid || result.score < 60) {
    return res.status(422).json({
      error: "Please provide a valid email address.",
      code: result.reason ?? "invalid_email",
    });
  }

  const user = await createUser({ email, password });
  res.json({ user });
});

And the equivalent for Python / FastAPI:

import os
import httpx
from fastapi import HTTPException

ENDPOINT = "https://api.mailbeam.dev/v1/verify"
HEADERS = {"Authorization": f"Bearer {os.environ['MAILBEAM_KEY']}"}


async def verify_email(email: str) -> dict:
    async with httpx.AsyncClient(timeout=3.0) as client:
        response = await client.post(ENDPOINT, json={"email": email}, headers=HEADERS)
        response.raise_for_status()
        return response.json()


@app.post("/api/signup")
async def signup(email: str, password: str):
    try:
        result = await verify_email(email)
    except httpx.HTTPError:
        # Same reasoning as above: our outage is not the user's problem.
        result = {"valid": True, "score": 100, "reason": None}

    if not result["valid"] or result["score"] < 60:
        raise HTTPException(
            status_code=422,
            detail=result["reason"] or "Please provide a valid email address.",
        )

    user = await create_user(email=email, password=password)
    return {"user": user}

Next steps