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 — Install an SDK

For production use, install one of our official SDKs:

# Node.js
npm install @mailbeam/sdk

# Python
pip install mailbeam

# PHP
composer require mailbeam/mailbeam-php

# Ruby
gem install mailbeam

# Go
go get github.com/mailbeam/mailbeam-go

Step 5 — Integrate into your signup

Here's a complete signup handler example for Node.js / Express:

import Mailbeam from "@mailbeam/sdk";

const mb = new Mailbeam({ apiKey: process.env.MAILBEAM_KEY });

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

  // Verify the email before creating the account
  const { valid, score, reason } = await mb.verify(email);

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

  // Proceed with account creation
  const user = await createUser({ email, password });
  res.json({ user });
});

And the equivalent for Python / FastAPI:

import mailbeam
from fastapi import HTTPException

mb = mailbeam.Client(api_key=os.environ["MAILBEAM_KEY"])

@app.post("/api/signup")
async def signup(email: str, password: str):
    result = await mb.verify(email)

    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