Mail API

NULL mail is a disposable email service at https://mail.nullnet.sh. You create an inbox, receive mail at it, read the mail over HTTP or a WebSocket, and the inbox expires on its own. The web app does everything through the public HTTP API at https://mail.nullnet.sh/v1, so your own code can do the same.

You can use inboxes without an account. An anonymous session token is enough. If you want inboxes that last longer, more inboxes, or premium features, create an account. Accounts are anonymous too: an account is a random account code plus a password. There is no email address, phone number or name on file, and no way to reset a password by email.

The machine-readable contract is the OpenAPI 3 document at /v1/openapi.json. It is generated from the handlers.

Conventions

• Base URL: https://mail.nullnet.sh/v1. Request and response bodies are JSON (Content-Type: application/json).
• Ids (inboxes, messages, webhooks, API keys, domains, sessions) are UUID strings.
• Timestamps are RFC 3339 strings in UTC, for example 2026-10-26T08:00:00Z.
• Sizes are integers in bytes. Durations are integers in seconds. The field name gives the unit (size_bytes, retention_secs).
• Money is USD as a decimal string with 18 fractional digits, for example "4.990000000000000000". The server never uses floating point. See Billing.
• If an endpoint's body is optional, you can send no body, an empty body or the JSON literal null.
• An inbox or message that belongs to someone else returns 404, never 403, so ids cannot be probed.

Authentication

There are three ways to call the API. A few endpoints need no credentials at all: GET /v1/domains, GET /v1/inboxes/available, GET /v1/billing/plans, GET /v1/billing/assets and GET /v1/passes/public-key.

Session tokens are 43-character base64url strings. A session lasts 30 days, and the expiry moves forward while the session is in use. Never put a token in a URL. The WebSocket also takes the token in its first message, not in the URL.

If a request carries both headers, the bearer token is used. A missing, expired or revoked token returns 401 unauthorized.

curl https://mail.nullnet.sh/v1/inboxes \
  -H "Authorization: Bearer {token}"

curl https://mail.nullnet.sh/v1/inboxes \
  -H "X-API-Key: {api_key}"

Tiers and limits

Every request resolves to one tier. The limits come from server configuration. Premium tiers are more generous because their configured numbers are higher. API responses use these tier names:

These are the current production limits for the tiers that can own inboxes:

A dash means the feature is not offered at that tier, or is not reachable with that credential: the WebSocket accepts session tokens only, and webhooks, custom domains and API keys are managed from a logged-in session.

Requests without credentials (anon_ip) get 30 requests per minute (burst 10) and 5 availability checks per minute. They cannot own inboxes. Login is limited to 10 attempts per hour per caller and also per account code. The SMTP receiver refuses any single message larger than 25 MiB, whatever the tier.

These numbers can change. GET /v1/account returns the resolved limits object for your account. In that object, an optional quota is null when the feature is not offered at your tier.

Limits for a logged-in account are counted per account, across all of its sessions. Registration, login, inbox creation and availability checks are also counted per client network (an IPv4 address, or an IPv6 /64) with the same numbers. Creating extra sessions does not buy more of them.

Rate limits and quotas

Responses that pass the tier limit carry X-RateLimit-Limit, the per-minute request limit of your tier.

Errors

Every error has the same body: an error object with a stable, machine-readable code and a human-readable message.

{
  "error": {
    "code": "unauthorized",
    "message": "authentication required"
  }
}

Pagination

Lists that can grow without bound (an inbox's messages, the credit ledger) use cursor pagination.

A page is an object with items (newest first) and next_cursor. next_cursor is null on the last page. A malformed cursor returns 400 bad_request. Other lists (inboxes, webhooks, API keys, deposits) are returned whole, as JSON arrays.

{
  "items": [],
  "next_cursor": null
}

CORS

The API allows browser requests from other origins only if the origin is on the server's list. Today the list has one entry, https://paste.nullnet.sh. The mail web app is served from the same origin as the API and needs no CORS. CORS does not affect server-side clients.

Allowed methods are GET, POST, PATCH, DELETE and OPTIONS. Allowed request headers are Authorization, Content-Type and X-API-Key. The API uses bearer tokens only. It sets no cookies, and CORS never allows credentials.

List domains

curl https://mail.nullnet.sh/v1/domains

[
  { "name": "mail.nullnet.sh" },
  { "name": "nullnet.sh" }
]

Quick start

# 1. Anonymous session
TOKEN=$(curl -s -X POST https://mail.nullnet.sh/v1/session | jq -r .token)

# 2. Inbox with a random address
INBOX=$(curl -s -X POST https://mail.nullnet.sh/v1/inboxes \
  -H "Authorization: Bearer $TOKEN")
echo "$INBOX" | jq -r .address    # e.g. kqv-7f3m2a@mail.nullnet.sh

# 3. Send mail to that address, then list it
curl -s https://mail.nullnet.sh/v1/inboxes/$(echo "$INBOX" | jq -r .id)/messages \
  -H "Authorization: Bearer $TOKEN"

Next: Accounts and sessions, Inboxes, Messages, and the WebSocket for live updates.