One POST, one inbox. Wait for the mail, read the code.

POST/api/v1/inboxes

Create an inbox. Send no body for a random name like quiet.fjord47, or JSON with a name and an optional domain. Answers 201 with the token, the inbox and Location: /api/v1/inbox.

409 address_unavailable when the name is taken or still locked; 422 validation_failed for a bad name or unknown domain; 422 name_reserved for names like postmaster.

curl -s -X POST https://nrthmail.com/api/v1/inboxes \
  -H "Content-Type: application/json" \
  -d "{\"name\":\"signup-test-$RANDOM\"}"

{
  "token": "nrth_3kQ9vR2mXc7LpT0aWb5YzN8sHd4FgJ6eUo1iKyMhPq7",
  "inbox": {
    "id": "ibx_01K6P8Z3QK4T2V9W1X5Y7A0C3D",
    "address": "signup-test-4821@nrthmail.com",
    "local_part": "signup-test-4821",
    "domain": "nrthmail.com",
    "custom": true,
    "status": "active",
    "created_at": "2026-10-03T19:44:19.123Z",
    "expires_at": "2026-10-04T19:44:19.123Z",
    "ttl_seconds": 86400,
    "message_count": 0,
    "unseen_count": 0
  }
}

POST/api/v1/inboxes/recover

Bring an expired inbox back with its old token. It returns empty, with a fresh 24 h. This works for 30 days after expiry. Burned inboxes stay gone: 410 gone. Unknown tokens get 404.

curl -s -X POST https://nrthmail.com/api/v1/inboxes/recover \
  -H "Content-Type: application/json" \
  -d '{"token":"nrth_…"}'

GET/api/v1/inbox

The inbox, with its counts and expiry. Returns: {"inbox": Inbox}

curl -s https://nrthmail.com/api/v1/inbox -H "Authorization: Bearer $TOKEN"
# {"inbox":{"address":"quiet.fjord47@nrthmail.com","status":"active","expires_at":"…",…}}

POST/api/v1/inbox/extend

Reset the expiry to now + 24 h. Returns: {"inbox": Inbox}

DELETE/api/v1/inbox

Burn the inbox: messages and files are deleted now, the address is locked for 30 days, and the token stops working. Answers 204.

curl -s -X DELETE https://nrthmail.com/api/v1/inbox -H "Authorization: Bearer $TOKEN"

GET/api/v1/domains

Domains you can create inboxes on. No token needed. Returns: {"domains":[{"domain":"nrthmail.com","default":true}]}

GET/api/v1/inbox/messages

Message summaries, newest first. Send the previous ETag back as If-None-Match and you get 304 when nothing changed: the cheapest way to poll.

curl -s "https://nrthmail.com/api/v1/inbox/messages?limit=10&unseen=true" \
  -H "Authorization: Bearer $TOKEN"

{
  "data": [
    {
      "id": "msg_01K6P9B7M2C4D8E6F0G3H5J7K9",
      "seq": 3,
      "received_at": "2026-10-03T19:46:02.481Z",
      "from": { "name": "GitHub", "address": "noreply@github.com" },
      "to": "quiet.fjord47+github@nrthmail.com",
      "tag": "github",
      "subject": "Your code is 482913",
      "preview": "Use 482913 to finish signing in…",
      "seen": false,
      "size": 18342,
      "has_attachments": false,
      "attachment_count": 0,
      "codes": ["482913"]
    }
  ],
  "next_cursor": null,
  "has_more": false
}

GET/api/v1/inbox/messages/{id}

One message in full: text, sanitized HTML, links, codes, headers, attachments and signed file URLs. Returns: {"message": Message}

curl -s https://nrthmail.com/api/v1/inbox/messages/msg_01K6P9B7M2C4D8E6F0G3H5J7K9 \
  -H "Authorization: Bearer $TOKEN"

PATCH/api/v1/inbox/messages/{id}

Mark a message seen or unseen. Body {"seen":true} as application/json or application/merge-patch+json. Returns the summary.

curl -s -X PATCH https://nrthmail.com/api/v1/inbox/messages/msg_01K6P9B7M2C4D8E6F0G3H5J7K9 \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" -d '{"seen":true}'

DELETE/api/v1/inbox/messages/{id}

Delete one message. Answers 204.

DELETE/api/v1/inbox/messages

Delete every message. The inbox and its address stay. Answers 204.

GET/api/v1/inbox/messages/{id}/raw

The original message as message/rfc822, served as a download named <id>.eml.

curl -s -OJ https://nrthmail.com/api/v1/inbox/messages/msg_01K6P9B7M2C4D8E6F0G3H5J7K9/raw \
  -H "Authorization: Bearer $TOKEN"

GET/api/v1/inbox/messages/{id}/attachments/{att_id}

One attachment as a download, with its original filename and X-Content-Type-Options: nosniff.

GET/api/v1/inbox/wait

The simplest way to get mail in a script: one request that hangs until a matching message arrives or the timeout passes. It returns at once if matching messages newer than since already exist.

Returns: {"messages":[Message…],"timed_out":false,"waited_ms":4210}. Messages are full Message objects.

Give your HTTP client a timeout longer than timeout. To loop without missing anything, pass the newest id you have seen as since.

# Wait for the next message from GitHub, up to 60 s.
curl -s "https://nrthmail.com/api/v1/inbox/wait?timeout=60&from=github" \
  -H "Authorization: Bearer $TOKEN"

const API = 'https://nrthmail.com/api/v1';
const auth = { Authorization: 'Bearer nrth_…' };

// Keep waiting, never miss one.
let since = new Date().toISOString();
for (;;) {
  const url = `${API}/inbox/wait?timeout=60&since=${encodeURIComponent(since)}`;
  const { messages } = await fetch(url, { headers: auth }).then((r) => r.json());
  for (const m of messages) console.log(m.subject, m.codes);
  if (messages.length) since = messages.map((m) => m.id).sort().at(-1);
}

import requests
from datetime import datetime, timezone

API = "https://nrthmail.com/api/v1"
auth = {"Authorization": "Bearer nrth_…"}

# Keep waiting, never miss one.
since = datetime.now(timezone.utc).isoformat(timespec="milliseconds").replace("+00:00", "Z")
while True:
    r = requests.get(f"{API}/inbox/wait", headers=auth, timeout=75,
                     params={"timeout": 60, "since": since})
    messages = r.json()["messages"]
    for m in messages:
        print(m["subject"], m["codes"])
    if messages:
        since = max(m["id"] for m in messages)

GET/api/v1/inbox/events

A Server-Sent Events stream that pushes every new message as it lands. Open it with the Authorization header from code that can stream a response (fetch, requests, curl). Native EventSource cannot send headers: get a ticket first and pass it as ?ticket=.

curl -N https://nrthmail.com/api/v1/inbox/events \
  -H "Authorization: Bearer $TOKEN"

# retry: 3000
#
# event: message
# id: msg_01K6P9B7M2C4D8E6F0G3H5J7K9
# data: {"id":"msg_01K6P9B7M2C4D8E6F0G3H5J7K9","seq":3,"subject":"Your code is 482913","codes":["482913"],…}
#
# : ping

const API = 'https://nrthmail.com/api/v1';
const token = 'nrth_…';

// Stream with fetch: the token stays in a header.
const res = await fetch(`${API}/inbox/events`, {
  headers: { Authorization: `Bearer ${token}`, Accept: 'text/event-stream' },
});
const reader = res.body.pipeThrough(new TextDecoderStream()).getReader();
let buffer = '';
for (;;) {
  const { value, done } = await reader.read();
  if (done) break;
  buffer += value;
  let end;
  while ((end = buffer.indexOf('\n\n')) >= 0) {
    const block = buffer.slice(0, end);
    buffer = buffer.slice(end + 2);
    let event = 'message', data = '';
    for (const line of block.split('\n')) {
      if (line.startsWith('event:')) event = line.slice(6).trim();
      else if (line.startsWith('data:')) data += line.slice(5).trim();
    }
    if (event === 'message' && data) console.log(JSON.parse(data).codes);
  }
}

// Native EventSource, with a ticket.
const { ticket } = await fetch(`${API}/inbox/tickets`, {
  method: 'POST', headers: { Authorization: `Bearer ${token}` },
}).then((r) => r.json());
const source = new EventSource(`${API}/inbox/events?ticket=${ticket}`);
source.addEventListener('message', (e) => console.log(JSON.parse(e.data).subject));
source.addEventListener('expired', () => source.close());
// Tickets are single use: on error, get a new one and reconnect.
source.onerror = () => source.close();

import json
import requests

API = "https://nrthmail.com/api/v1"
auth = {"Authorization": "Bearer nrth_…", "Accept": "text/event-stream"}

# Stream with requests.
with requests.get(f"{API}/inbox/events", headers=auth, stream=True, timeout=(10, 90)) as r:
    event, data = "message", ""
    for line in r.iter_lines(decode_unicode=True):
        if line.startswith("event:"):
            event = line[6:].strip()
        elif line.startswith("data:"):
            data += line[5:].strip()
        elif line == "":
            if event == "message" and data:
                print(json.loads(data)["codes"])
            event, data = "message", ""

POST/api/v1/inbox/tickets

A single-use ticket for EventSource, valid 60 s. Get a fresh one for every reconnect. Returns: {"ticket":"tk_…","expires_at":"…"}

POST/api/v1/inbox/share

Create a share code. url is https://nrthmail.com/#share=CODE; the code sits in the fragment, which browsers never send to a server. Returns: {"code","url","expires_at"}

POST/api/v1/share/{code}

Redeem a share code. No token needed. Returns the token and the inbox; 404 when the code is unknown, used or expired.

GET/api/v1/inbox/qr.svg

A QR code (SVG) of a fresh share URL. Every call makes a new code; X-Share-Expires says when it stops working. Modules are #000 on a transparent background: show it on a light surface.

curl -s -X POST https://nrthmail.com/api/v1/inbox/share -H "Authorization: Bearer $TOKEN"
# {"code":"K7QF2M9XWD4A","url":"https://nrthmail.com/#share=K7QF2M9XWD4A","expires_at":"2026-10-03T19:48:19.123Z"}

# On the other device, no token needed:
curl -s -X POST https://nrthmail.com/api/v1/share/K7QF2M9XWD4A

curl -s https://nrthmail.com/api/v1/inbox/qr.svg -o inbox-qr.svg \
  -H "Authorization: Bearer $TOKEN"

GET/api/v1/stats

Public counters for the whole service. Returns: {"messages_24h":1204,"inboxes_24h":311,"inboxes_active":97}

GET/api/v1/openapi.json

An OpenAPI 3.1 description of everything on this page, for code generators and API clients.

The full machine-readable description lives at /api/v1/openapi.json.