Inboxes

An inbox is one email address. It belongs to the session that created it, or to the account if the session was logged in, and it expires after the retention period of your tier. Reading an inbox counts as activity and pushes its expiry forward.

Inbox endpoints accept a session token or an API key. An inbox owned by someone else returns 404.

The inbox model

Addresses

• Addresses are lowercased. A +tag is ignored when resolving an address: mail to bob+news@nullnet.sh arrives at bob@nullnet.sh.
• Without a chosen local part, the server picks a random one: three letters, a dash and six letters or digits (kqv-7f3m2a).
• A local part is at most 64 characters of the usual address characters, with no leading, trailing or doubled dot.
• Reserved addresses. On the system domains, these local parts belong to the operator and cannot be created or claimed: info, postmaster, abuse, admin, administrator, hostmaster, webmaster, security, support, root, noreply, no-reply, billing, sales. Creating one returns 409 conflict, and availability is always false.
• Unclaimed mail. Mail to an address on a system domain that nobody has created yet is kept in an unowned inbox for 30 minutes. Creating that address claims it, with the mail already received.

Check availability

curl -G https://mail.nullnet.sh/v1/inboxes/available \
  -d local=alice \
  -d domain=nullnet.sh

{ "available": true }

Create an inbox

curl https://mail.nullnet.sh/v1/inboxes \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{"local": "alice", "domain": "nullnet.sh"}'

{
  "id": "019a2f50-1c3d-7e41-8b2a-4f6d8e0a1c3b",
  "address": "alice@nullnet.sh",
  "expires_at": "2026-10-26T09:00:00Z",
  "retention_secs": 3600,
  "message_count": 0,
  "storage_bytes": 0,
  "created_at": "2026-10-26T08:00:00Z"
}

List inboxes

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

[
  {
    "id": "019a2f50-1c3d-7e41-8b2a-4f6d8e0a1c3b",
    "address": "alice@nullnet.sh",
    "expires_at": "2026-10-26T09:00:00Z",
    "retention_secs": 3600,
    "message_count": 3,
    "storage_bytes": 48211,
    "created_at": "2026-10-26T08:00:00Z"
  }
]

Get an inbox

curl https://mail.nullnet.sh/v1/inboxes/019a2f50-1c3d-7e41-8b2a-4f6d8e0a1c3b \
  -H "Authorization: Bearer {token}"

Extend an inbox

curl -X POST https://mail.nullnet.sh/v1/inboxes/019a2f50-1c3d-7e41-8b2a-4f6d8e0a1c3b/extend \
  -H "Authorization: Bearer {token}"

Delete an inbox

curl -X DELETE https://mail.nullnet.sh/v1/inboxes/019a2f50-1c3d-7e41-8b2a-4f6d8e0a1c3b \
  -H "Authorization: Bearer {token}"

Custom domains

Premium accounts can receive mail on their own domains (up to 10). Other tiers get 403 tier_required. Custom domains are managed from a logged-in session, not with an API key.

1. Register the domain with POST /v1/domains. The response lists two DNS records to publish: an MX record pointing at the NULL mail server, and a TXT record grrla-verify=<token> at _grrla.<domain>.
2. Publish both records at your DNS provider.
3. Call POST /v1/domains/:id/verify. The domain is verified when the TXT token matches and an MX record points at the server.

Until a domain is verified, mail to it is refused and inboxes cannot be created on it. A registration that is not verified within seven days is dropped and the name is freed. Verified domains are re-checked daily. If the TXT or MX record disappears, the domain becomes unverified and mail is refused again until verify passes.

On a verified custom domain, every address belongs to you. Only you can create inboxes on it, reserved local parts do not apply, and mail to an address you have not created yet creates an inbox owned by your account, with your retention.

The custom domain model

Register a custom domain

curl https://mail.nullnet.sh/v1/domains \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{"name": "mail.example.com"}'

{
  "id": "019a2f52-7a10-7c33-9e4b-2d5f7a9c1e3f",
  "name": "mail.example.com",
  "verified": false,
  "verified_at": null,
  "created_at": "2026-10-26T08:00:00Z",
  "dns": [
    { "kind": "MX", "name": "mail.example.com", "value": "10 mail.nullnet.sh" },
    { "kind": "TXT", "name": "_grrla.mail.example.com", "value": "grrla-verify=4f1c9a7e2b6d8f0a3c5e7b9d1f2a4c6e" }
  ]
}

List your custom domains

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

Verify a custom domain

curl -X POST https://mail.nullnet.sh/v1/domains/019a2f52-7a10-7c33-9e4b-2d5f7a9c1e3f/verify \
  -H "Authorization: Bearer {token}"

{
  "verified": true,
  "txt_ok": true,
  "mx_ok": true,
  "txt_found": ["grrla-verify=4f1c9a7e2b6d8f0a3c5e7b9d1f2a4c6e"],
  "mx_found": ["mail.nullnet.sh"],
  "error": null
}

Remove a custom domain

curl -X DELETE https://mail.nullnet.sh/v1/domains/019a2f52-7a10-7c33-9e4b-2d5f7a9c1e3f \
  -H "Authorization: Bearer {token}"