Authentication

Mailbeam uses API keys to authenticate requests. All requests must include a valid API key in the Authorization header.

Bearer token

Include your API key as a Bearer token in every request:

Authorization: Bearer mb_live_xxxxxxxxxxxxxxxxxxxx

Example with cURL:

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

Key prefixes

Mailbeam API keys use a prefix to indicate their environment:

Use mb_test_ keys during development and CI. Test keys return fixed responses based on the email domain:

• @valid.mailbeam-test.dev → always returns { valid: true, score: 99 }
• @invalid.mailbeam-test.dev → always returns { valid: false, score: 0 }
• @disposable.mailbeam-test.dev → always returns { valid: false, disposable: true }

Environment variables

Never hard-code API keys in your source code. Use environment variables:

# .env.local
MAILBEAM_KEY=mb_live_xxxxxxxxxxxxxxxxxxxx

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

Key rotation

You should rotate API keys periodically or immediately if a key is compromised:

1. Go to the API Keys page in your dashboard
2. Click Create key to generate a new key
3. Update your application with the new key
4. Click Revoke on the old key once traffic has moved over

Revoking a key immediately invalidates it. Requests using the revoked key will return 401 Unauthorized.

Multiple keys

You can create up to 10 API keys per account. We recommend:

• One key per environment (development, staging, production)
• One key per application if you run multiple services
• Rotate keys when team members leave

Error responses