Introduction
Every call goes to this base address:
https://boltmail.us/api/v1Requests 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):
Authorization: Bearer YOUR_API_KEYKeys 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.
Quick start
The most common job: get an address, give it to a website, wait for the email, read the code.
# 1) create a random mailbox
curl -X POST https://boltmail.us/api/v1/mailboxes \
-H "Authorization: Bearer YOUR_API_KEY"
# 2) wait for the next email (long poll, up to 25 s)
curl "https://boltmail.us/api/v1/mailboxes/happy.otter@example.com/wait?timeout=25" \
-H "Authorization: Bearer YOUR_API_KEY"
# 3) read it (text, html, links and verification codes)
curl https://boltmail.us/api/v1/mailboxes/happy.otter@example.com/messages/123 \
-H "Authorization: Bearer YOUR_API_KEY"<?php
// Download BoltMailClient.php (link above) and put it next to this file.
require 'BoltMailClient.php';
$bm = new BoltMailClient(getenv('BOLTMAIL_KEY'), 'https://boltmail.us');
$box = $bm->createMailbox(); // random address
echo "Use this address: {$box['address']}\n";
// ... submit $box['address'] to the website you are testing ...
$mail = $bm->waitForMessage($box['address'], 60); // null if nothing arrives in 60 s
if ($mail) {
$full = $bm->message($box['address'], $mail['id']);
echo "Subject: {$full['subject']}\n";
echo "Code: " . ($full['codes'][0] ?? 'none found') . "\n";
}
$bm->deleteMailbox($box['address']); // clean up// Node.js 18+ (built-in fetch). Run it on your server, never in the browser.
const BASE = 'https://boltmail.us/api/v1';
const headers = { Authorization: `Bearer ${process.env.BOLTMAIL_KEY}`, 'Content-Type': 'application/json' };
async function api(path, options = {}) {
const res = await fetch(BASE + path, { headers, ...options });
if (res.status === 204) return null;
const data = await res.json();
if (!res.ok) throw new Error(`${data.error.code}: ${data.error.message}`);
return data;
}
const box = await api('/mailboxes', { method: 'POST' });
console.log('Use this address:', box.address);
const wait = await api(`/mailboxes/${box.address}/wait?timeout=25`);
if (wait.messages.length) {
const mail = await api(`/mailboxes/${box.address}/messages/${wait.messages[0].id}`);
console.log(mail.subject, mail.codes);
}
await api(`/mailboxes/${box.address}`, { method: 'DELETE' });import os, requests
BASE = "https://boltmail.us/api/v1"
s = requests.Session()
s.headers["Authorization"] = "Bearer " + os.environ["BOLTMAIL_KEY"]
def call(method, path, **kw):
r = s.request(method, BASE + path, timeout=40, **kw)
if r.status_code == 204:
return None
data = r.json()
if not r.ok:
raise RuntimeError(f'{data["error"]["code"]}: {data["error"]["message"]}')
return data
box = call("POST", "/mailboxes")
print("Use this address:", box["address"])
wait = call("GET", f'/mailboxes/{box["address"]}/wait', params={"timeout": 25})
if wait["messages"]:
mail = call("GET", f'/mailboxes/{box["address"]}/messages/{wait["messages"][0]["id"]}')
print(mail["subject"], mail["codes"])
call("DELETE", f'/mailboxes/{box["address"]}')package main
import (
"encoding/json"
"fmt"
"net/http"
"os"
)
const base = "https://boltmail.us/api/v1"
func call(method, path string, out interface{}) error {
req, _ := http.NewRequest(method, base+path, nil)
req.Header.Set("Authorization", "Bearer "+os.Getenv("BOLTMAIL_KEY"))
res, err := http.DefaultClient.Do(req)
if err != nil {
return err
}
defer res.Body.Close()
if res.StatusCode >= 400 {
return fmt.Errorf("api error: HTTP %d", res.StatusCode)
}
if out != nil && res.StatusCode != 204 {
return json.NewDecoder(res.Body).Decode(out)
}
return nil
}
func main() {
var box struct{ Address string `json:"address"` }
if err := call("POST", "/mailboxes", &box); err != nil {
panic(err)
}
fmt.Println("Use this address:", box.Address)
_ = call("DELETE", "/mailboxes/"+box.Address, nil)
}require "net/http"
require "json"
BASE = URI("https://boltmail.us/api/v1")
def call(method, path, body = nil)
uri = URI("#{BASE}#{path}")
req = Net::HTTP.const_get(method.capitalize).new(uri)
req["Authorization"] = "Bearer #{ENV['BOLTMAIL_KEY']}"
req["Content-Type"] = "application/json"
req.body = body.to_json if body
res = Net::HTTP.start(uri.host, uri.port, use_ssl: true) { |h| h.request(req) }
return nil if res.code == "204"
data = JSON.parse(res.body)
raise "#{data['error']['code']}: #{data['error']['message']}" if res.code.to_i >= 400
data
end
box = call("post", "/mailboxes")
puts "Use this address: #{box['address']}"
wait = call("get", "/mailboxes/#{box['address']}/wait?timeout=25")
puts wait["messages"].first&.fetch("subject")
call("delete", "/mailboxes/#{box['address']}")PHP library
A single-file client with retries, clear exceptions and a waitForMessage() helper. Works on PHP 7.4+ with cURL.
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
/statusService health. No API key needed.
{ "status": "ok", "version": "1", "time": "2026-11-11T09:00:00+00:00" }/meYour key: name, rate limit, how many mailboxes you hold and may hold.
{ "name": "My app", "key_prefix": "bm_3fa9c2d1", "rate_limit_per_minute": 60,
"mailboxes": { "used": 3, "max": 50 }, "expires_at": null, "allowed_ips": null }/domainsThe domains you can create addresses on.
{ "domains": ["example.com", "mail.example.net"] }/mailboxesCreate a mailbox. Send nothing for a random address (any domain), or choose the parts yourself.
| Parameter | Type | Description |
|---|---|---|
username | string, optional | Letters, numbers, . _ + - (max 64). Random when omitted. |
domain | string, optional | One of GET /domains. Random when omitted. |
{ "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=..." }/mailboxesList the mailboxes created with this key (newest first).
| Parameter | Type | Description |
|---|---|---|
limit | integer | 1 to 100, default 50. |
offset | integer | Default 0. |
{ "mailboxes": [ { "address": "happy.otter@example.com", ... } ], "total": 3, "limit": 50, "offset": 0 }/mailboxes/{address}One mailbox with its message counts.
{ "address": "happy.otter@example.com", "messages": 2, "unread": 1, ... }/mailboxes/{address}Delete the mailbox and every message in it. The address becomes free again.
HTTP 204 (no body)/mailboxes/{address}/messagesList messages, newest first. Bodies are not included (use the single-message call).
| Parameter | Type | Description |
|---|---|---|
limit | integer | 1 to 100, default 50. |
after_id | integer | Only messages with a higher id (for polling). |
unread | boolean | true = unread only. |
order | string | asc or desc (default desc). |
{ "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 }/mailboxes/{address}/messages/{id}One message in full. Marks it as read unless you pass mark_read=false.
| Parameter | Type | Description |
|---|---|---|
mark_read | boolean | Default true. |
{ "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"] }/mailboxes/{address}/messages/{id}Mark a message as read or unread.
| Parameter | Type | Description |
|---|---|---|
read | boolean, required | true or false (JSON body). |
The updated message (summary form)./mailboxes/{address}/messages/{id}Delete one message.
HTTP 204 (no body)/mailboxes/{address}/waitLong poll: returns as soon as a message newer than after_id exists, or after the timeout. Perfect for "wait for my verification email".
| Parameter | Type | Description |
|---|---|---|
timeout | integer | Seconds to wait, 1 to 25 (default 20). |
after_id | integer | Only newer messages. Default: only mail that arrives from now on. |
{ "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 carriesX-RateLimit-Limit,X-RateLimit-RemainingandX-RateLimit-Reset. Over the limit you get429and aRetry-Afterheader. - 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": { "code": "mailbox_not_found", "message": "No mailbox with that address belongs to this API key.", "status": 404 } }| Status | Codes | Meaning |
|---|---|---|
| 400 | invalid_json / invalid_address / https_required | The request is malformed. |
| 401 | unauthorized / invalid_key | No key was sent, or the key is wrong, revoked or expired. |
| 403 | forbidden_ip / mailbox_limit / mailbox_suspended | The key may not be used from this IP, it already holds its maximum number of mailboxes, or the mailbox is suspended. |
| 404 | mailbox_not_found / message_not_found / not_found | Nothing with that address or id belongs to your key. |
| 409 | address_taken | Someone already uses that address. |
| 422 | invalid_username / invalid_domain / username_forbidden / invalid_field | A value was rejected. The message says which one. |
| 429 | rate_limited / too_many_failures / quota_exceeded | Slow down, or (quota_exceeded) your plan's monthly requests are used up. The Retry-After header says how many seconds to wait. |
| 503 | api_disabled / maintenance / unavailable | The 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:
https://boltmail.us/api/v1/openapi.json







