Home / API

The BoltMail API

Create disposable mailboxes, wait for an email and read its verification code, all from your own code. A small, secure REST API with JSON in and out.

REST + JSONHTTPS only Long-poll "wait for mail"OpenAPI 3

Get your free API key in a minute

Free Basic plan included. Upgrade for more requests, mailboxes and keys. Pay by card, PayPal or crypto.

See plans Create free account

Introduction

Every call goes to this base address:

Base URL
https://boltmail.us/api/v1

Requests and responses are JSON (UTF-8). Times are ISO 8601 in UTC. Each API key can only see and change the mailboxes it created itself, so keys never interfere with each other.

Need a key? Contact us: support@boltmail.us.

Authentication

Send your key in the Authorization header of every request (except /status):

Header
Authorization: Bearer YOUR_API_KEY

Keys look like bm_ followed by 40 characters. X-API-Key: YOUR_API_KEY is accepted as well. Keys are never accepted in the URL, because URLs end up in logs and browser history.

Keep it secret. Call the API from your server or CI job. Anyone holding the key can use your quota. If it leaks, ask for it to be revoked and get a new one.

Quick start

The most common job: get an address, give it to a website, wait for the email, read the code.

PHP library

A single-file client with retries, clear exceptions and a waitForMessage() helper. Works on PHP 7.4+ with cURL.

Download BoltMailClient.php

More examples
require 'BoltMailClient.php';

try {
    $bm = new BoltMailClient(getenv('BOLTMAIL_KEY'), 'https://boltmail.us');
    print_r($bm->me());                       // your limits
    print_r($bm->domains());                  // available domains

    $box  = $bm->createMailbox('signup-test'); // choose the name (and optionally a domain)
    $list = $bm->messages($box['address'], ['unread' => true, 'limit' => 10]);
    $bm->markRead($box['address'], 123);
} catch (BoltMailException $e) {
    echo $e->errorCode . ' (HTTP ' . $e->httpStatus . '): ' . $e->getMessage();
}

Endpoints

GET/status

Service health. No API key needed.

Example response
{ "status": "ok", "version": "1", "time": "2026-11-11T09:00:00+00:00" }
GET/me

Your key: name, rate limit, how many mailboxes you hold and may hold.

Example response
{ "name": "My app", "key_prefix": "bm_3fa9c2d1", "rate_limit_per_minute": 60,
  "mailboxes": { "used": 3, "max": 50 }, "expires_at": null, "allowed_ips": null }
GET/domains

The domains you can create addresses on.

Example response
{ "domains": ["example.com", "mail.example.net"] }
POST/mailboxes

Create a mailbox. Send nothing for a random address (any domain), or choose the parts yourself.

ParameterTypeDescription
usernamestring, optionalLetters, numbers, . _ + - (max 64). Random when omitted.
domainstring, optionalOne of GET /domains. Random when omitted.
Example response
{ "address": "happy.otter@example.com", "username": "happy.otter", "domain": "example.com",
  "status": "active", "created_at": "2026-11-11T09:00:00+00:00", "messages": 0, "unread": 0,
  "web_link": "https://boltmail.us/?k=..." }
GET/mailboxes

List the mailboxes created with this key (newest first).

ParameterTypeDescription
limitinteger1 to 100, default 50.
offsetintegerDefault 0.
Example response
{ "mailboxes": [ { "address": "happy.otter@example.com", ... } ], "total": 3, "limit": 50, "offset": 0 }
GET/mailboxes/{address}

One mailbox with its message counts.

Example response
{ "address": "happy.otter@example.com", "messages": 2, "unread": 1, ... }
DELETE/mailboxes/{address}

Delete the mailbox and every message in it. The address becomes free again.

Response
HTTP 204 (no body)
GET/mailboxes/{address}/messages

List messages, newest first. Bodies are not included (use the single-message call).

ParameterTypeDescription
limitinteger1 to 100, default 50.
after_idintegerOnly messages with a higher id (for polling).
unreadbooleantrue = unread only.
orderstringasc or desc (default desc).
Example response
{ "messages": [ { "id": 123, "from": { "address": "no-reply@site.com", "name": "Site" },
    "subject": "Your code", "received_at": "2026-11-11T09:01:10+00:00", "read": false,
    "preview": "Your verification code is 482913" } ], "total": 1, "limit": 50 }
GET/mailboxes/{address}/messages/{id}

One message in full. Marks it as read unless you pass mark_read=false.

ParameterTypeDescription
mark_readbooleanDefault true.
Example response
{ "id": 123, "from": {...}, "subject": "Your code", "read": true, "preview": "...",
  "text": "Your verification code is 482913", "html": "<p>...</p>",
  "links": ["https://site.com/verify?t=..."], "codes": ["482913"] }
PATCH/mailboxes/{address}/messages/{id}

Mark a message as read or unread.

ParameterTypeDescription
readboolean, requiredtrue or false (JSON body).
Example response
The updated message (summary form).
DELETE/mailboxes/{address}/messages/{id}

Delete one message.

Response
HTTP 204 (no body)
GET/mailboxes/{address}/wait

Long poll: returns as soon as a message newer than after_id exists, or after the timeout. Perfect for "wait for my verification email".

ParameterTypeDescription
timeoutintegerSeconds to wait, 1 to 25 (default 20).
after_idintegerOnly newer messages. Default: only mail that arrives from now on.
Example response
{ "messages": [ { "id": 124, ... } ], "timed_out": false, "last_id": 124 }

{address} is the full email address, for example happy.otter@example.com (URL-encode it if your library does not do it for you).

Limits and security

  • Rate limit. Each key has a requests-per-minute limit (see GET /me). Every response carries X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset. Over the limit you get 429 and a Retry-After header.
  • Mailbox limit. A key holds at most the number of mailboxes shown in GET /me. Delete the ones you no longer need. Creating is also capped at 30 per minute.
  • Automatic clean-up. Messages are deleted after the site's retention time, and mailboxes that received no mail for a while are released. Do not use an address as a permanent inbox.
  • Isolation. Other keys' mailboxes answer 404, exactly like addresses that do not exist.
  • IP allow-list and expiry. A key can be restricted to your server's IP addresses and given an expiry date.
  • HTTPS only. Plain HTTP requests are refused. Keys are stored as one-way hashes on our side.
  • Repeated wrong keys from one IP are blocked for a minute.

Errors

Failed calls use a normal HTTP status and a JSON body:

Error format
{ "error": { "code": "mailbox_not_found", "message": "No mailbox with that address belongs to this API key.", "status": 404 } }
StatusCodesMeaning
400invalid_json / invalid_address / https_requiredThe request is malformed.
401unauthorized / invalid_keyNo key was sent, or the key is wrong, revoked or expired.
403forbidden_ip / mailbox_limit / mailbox_suspendedThe key may not be used from this IP, it already holds its maximum number of mailboxes, or the mailbox is suspended.
404mailbox_not_found / message_not_found / not_foundNothing with that address or id belongs to your key.
409address_takenSomeone already uses that address.
422invalid_username / invalid_domain / username_forbidden / invalid_fieldA value was rejected. The message says which one.
429rate_limited / too_many_failures / quota_exceededSlow down, or (quota_exceeded) your plan's monthly requests are used up. The Retry-After header says how many seconds to wait.
503api_disabled / maintenance / unavailableThe API is switched off or the service is being maintained. Retry later.

OpenAPI

Import the machine-readable description into Postman, Insomnia or a code generator:

OpenAPI 3 document
https://boltmail.us/api/v1/openapi.json