MailboxTemp API

Everything the MailboxTemp inbox page does goes through this public HTTP API, and you can use it directly: create a disposable inbox, point your signup flow at it, and read the verification message — with any one-time code already extracted for you. It's free, requires no API key, and is built for automated email-verification and OTP testing.

Basics

Base URL: https://mailboxtemp.com
Authentication: none for the endpoints below. Possession of an inbox address is the credential — every message read/delete is scoped to the address you supply, so you can only access inboxes whose address you know. Treat addresses like bearer tokens; see the privacy model.
Format: JSON in, JSON out. Every response has an ok boolean; failures add an error code.
CORS: open (no credentials), so you can call it from browser code as well as servers.
Retention: free inboxes live 60 minutes (extendable +10 min at a time), Pro inboxes 24 hours. On expiry, the inbox, messages, and attachments are permanently deleted — plan your tests accordingly.

Rate limits

Scope	Limit	On exceeding
Inbox creation (`/api/inbox/generate`)	20 requests / minute / IP	`429` with `{"ok":false,"error":"RATE_LIMITED"}`
Reads and other inbox/email calls	100 requests / minute / IP	`429` with `{"ok":false,"error":"RATE_LIMITED"}`

Prefer the WebSocket stream over tight polling loops — it's faster for you and cheaper for everyone.

Endpoints

POST /api/inbox/generate

Create a new disposable inbox on one of the active domains. No body required.

curl -X POST https://mailboxtemp.com/api/inbox/generate

{
  "ok": true,
  "address": "k3x91qa@fakhita.xyz",
  "expires": "2026-08-23T18:23:26.684Z",
  "inboxId": "0177695b-7bb8-4f1c-9427-0669199be808"
}

Passing a prefix in the JSON body (a custom local part) is a Pro feature and returns 403 {"ok":false,"error":"PRO_REQUIRED"} without a Pro session.

GET /api/inbox/{address}

Inbox metadata and remaining lifetime. ttl is seconds until expiry.

{
  "ok": true,
  "id": "0177695b-…",
  "address": "k3x91qa@fakhita.xyz",
  "tier": "free",
  "expires_at": "2026-08-23T18:23:26.684Z",
  "ttl": 2418
}

Unknown or expired-and-purged addresses return 404 {"ok":false,"error":"NOT_FOUND"}.

POST /api/inbox/{address}/extend

Extend a live inbox by 10 minutes. Returns {"ok":true}. Extending an already-expired inbox has no effect.

GET /api/inbox/{address}/emails

List the inbox's messages, newest first (up to 50). otp_code is the auto-detected one-time code, or null if none was found.

{
  "ok": true,
  "emails": [
    {
      "id": "8ddfa2b4-…",
      "from_address": "no-reply@example-app.com",
      "from_name": "Example App",
      "subject": "Your verification code",
      "otp_code": "482913",
      "has_attachments": false,
      "read": false,
      "received_at": "2026-08-23T17:23:43.840Z"
    }
  ]
}

GET /api/email/{address}/{id}

Fetch one message in full — sanitized HTML body, plain-text body, and attachment metadata. Fetching marks the message as read.

{
  "ok": true,
  "email": {
    "id": "8ddfa2b4-…",
    "from_address": "no-reply@example-app.com",
    "subject": "Your verification code",
    "body_html": "<p>Your code is 482913</p>",
    "body_text": "Your code is 482913",
    "otp_code": "482913",
    "read": true,
    "received_at": "2026-08-23T17:23:43.840Z"
  },
  "attachments": [
    { "id": "…", "filename": "invoice.pdf", "mime_type": "application/pdf", "size_bytes": 48213, "url": "…" }
  ]
}

DELETE /api/email/{address}/{id}

Delete one message (and its attachments) immediately, before the inbox's natural expiry. Returns {"ok":true}, or 404 if the message doesn't exist in that inbox.

Real-time: WebSocket

Instead of polling, open a WebSocket to be pushed new messages the moment they're stored:

const ws = new WebSocket(
  'wss://mailboxtemp.com/ws/inbox?address=k3x91qa@fakhita.xyz'
);
ws.onmessage = (ev) => {
  const msg = JSON.parse(ev.data);
  // {type:"connected"} on open, then one event per arriving email
};

Error codes

HTTP	`error`	Meaning
404	`NOT_FOUND`	Address or message doesn't exist (or was already purged after expiry).
429	`RATE_LIMITED`	Per-IP limit exceeded — back off and retry after a minute.
403	`PRO_REQUIRED`	Custom prefixes require a Pro account.
400	`ADDRESS_TAKEN`, `INVALID_PREFIX`, …	Generation-time validation failures.
500	message	Server-side failure; safe to retry.

Node.js client

For test suites there's a small zero-dependency client, mailboxtemp on npm, with pollers made for end-to-end tests:

npm install mailboxtemp

const { MailboxTemp } = require('mailboxtemp');
const mt = new MailboxTemp();

const inbox = await mt.createInbox();
// … register inbox.address in the flow under test …
const code = await mt.waitForOtp(inbox.address, { timeoutMs: 60000 });

More background on using disposable inboxes in CI is in disposable email for developers.

Acceptable use

The API exists for legitimate receiving: signup testing, QA automation, and personal privacy. Inboxes are receive-only — nothing can be sent from them — and message intake is capped at 10 MB. Don't use the API to evade bans, harass, defraud, or violate another service's terms; abusive usage patterns are rate-limited and blocked, per our Terms of Service. If you're building something unusual on top of the API, tell us — we'd rather help than block you.

Open the live inbox →