Disposable Email API

TempMailPortal exposes the same JSON API that powers this website. Create a temporary inbox, poll it for incoming mail, and read messages — all over plain HTTPS, with no signup and no API key. It's free, CORS-enabled (call it straight from the browser or any backend), and receive-only — built for testing your own sign-up and verification flows, QA, and test fixtures. Please review the acceptable-use rules below before you build on it.

Acceptable use

The API is free and key-less to keep legitimate testing and privacy use frictionless. By using it you agree to our Terms of Service.

Allowed — for example:

• Testing your own registration and email-verification flow end to end.
• QA-testing passwordless or magic-link login in an app you control.
• Checking how your email templates render during development.
• Safely demoing email notifications without using real personal inboxes.

Prohibited:

• Mass or automated account creation on third-party services.
• Free-trial, coupon, or signup-bonus abuse.
• OTP/verification-code abuse, fraud, phishing, or impersonation.
• Spam, ban evasion, scraping sign-up systems, or bypassing another platform's rules.

The API applies rate limits to reduce automated abuse. Report specific misuse, including the address and timestamps, to abuse@tempmailportal.com; available action depends on the evidence and controls the service can verify.

How it works

1. Create an inbox — POST /api/inbox returns a random address and a token.
2. Poll for mail — call GET /api/messages with that token every few seconds.
3. Read a message — GET /api/messages/{id} returns the full HTML and text body.

The token is the only credential — keep it for as long as you want to use that inbox. There are no accounts and nothing to manage.

Quick start

# 1. Create a throwaway inbox
curl -X POST https://api.tempmailportal.com/api/inbox
# → {"address":"24jab274te@ynoxa.com","token":"MjRqYWIyNzR0ZQ.6pIj…"}

# 2. Check the inbox (use the token from step 1)
curl https://api.tempmailportal.com/api/messages \
  -H "Authorization: Bearer YOUR_TOKEN"
# → []   (empty until mail arrives)

# 3. Read one message in full, by id
curl https://api.tempmailportal.com/api/messages/MESSAGE_ID \
  -H "Authorization: Bearer YOUR_TOKEN"

Authentication

POST /api/inbox hands you a bearer token tied to that one mailbox. Send it on every read or delete call:

Authorization: Bearer YOUR_TOKEN

The token is a stateless signed value — it does not expire, but the mail it can read does (see limits). No API key is required for the public browser flow. Note that the email address itself is public and guessable: anyone who creates the same local-part receives the same mail, so never use a disposable inbox for anything sensitive.

Endpoints

Returns the mailbox domains currently available. Domains are rotated over time, so fetch this list rather than hard-coding a domain.

curl https://api.tempmailportal.com/api/domains
→ 200 ["ynoxa.com"]

Creates an inbox and returns its address and access token. The JSON body is optional:

• domain — one of the values from /api/domains. Defaults to the first domain if omitted or unknown.
• login — a custom local-part (the part before @). Sanitized to lowercase a–z 0–9 . _ -, max 30 chars. Omit it for a random address.

curl -X POST https://api.tempmailportal.com/api/inbox \
  -H "Content-Type: application/json" \
  -d '{"login":"my-alias","domain":"ynoxa.com"}'
→ 200 {"address":"my-alias@ynoxa.com","token":"…"}

Lists message envelopes for the token's mailbox, newest first. Envelopes are lightweight — no body — so they're cheap to poll.

curl https://api.tempmailportal.com/api/messages \
  -H "Authorization: Bearer YOUR_TOKEN"
→ 200
[
  {
    "id": "2b1f…-uuid",
    "from": "noreply@example.com",
    "fromName": "Example",
    "subject": "Your verification code",
    "intro": "Your code is 123456 …",
    "date": "2026-06-05T12:34:56.000Z"
  }
]

Returns one full message, scoped to the token's mailbox. Responds 404 if the id doesn't belong to this inbox or has expired.

curl https://api.tempmailportal.com/api/messages/2b1f…-uuid \
  -H "Authorization: Bearer YOUR_TOKEN"
→ 200
{
  "id": "2b1f…-uuid",
  "from": "noreply@example.com",
  "fromName": "Example",
  "subject": "Your verification code",
  "date": "2026-06-05T12:34:56.000Z",
  "html": "<p>Your code is 123456</p>",
  "text": "Your code is 123456",
  "attachments": [
    { "filename": "invoice.pdf", "mimeType": "application/pdf", "size": 28451, "downloadable": false }
  ]
}

The attachments array always lists available metadata. downloadable is true only when the file was retained in attachment storage; do not assume an attachment can be downloaded unless that field is true.

Immediately deletes every message in the token's mailbox.

curl -X DELETE https://api.tempmailportal.com/api/inbox \
  -H "Authorization: Bearer YOUR_TOKEN"
→ 200 {"ok":true}

Errors

Errors return the matching HTTP status and a JSON body of the form {"error":"…"}:

Limits & fair use

• Receive-only. The API cannot send email — by design.
• Messages auto-expire ~24 hours after they arrive and are then permanently deleted. The token keeps working; the old mail is simply gone.
• Open CORS (Access-Control-Allow-Origin: *) — you can call every endpoint directly from client-side JavaScript.
• Inbox creation and domain discovery: up to 30 requests per minute for each action and source address.
• Mailbox reads and deletion: up to 120 requests per minute per mailbox token. Poll every 8–10 seconds; do not use a tight loop.
• API-key traffic: up to 600 requests per minute per key, plus the key's configured daily plan limit.
• Don't use it for spam, fraud, or anything prohibited by our Terms of Service.

Full example (JavaScript)

Works in the browser or in Node 18+ (both have fetch built in):

const API = "https://api.tempmailportal.com";

// 1. Create an inbox
const { address, token } =
  await (await fetch(`${API}/api/inbox`, { method: "POST" })).json();
console.log("Inbox ready:", address);

// 2. Poll until the first message arrives, then read it in full
const timer = setInterval(async () => {
  const auth = { headers: { Authorization: `Bearer ${token}` } };
  const list = await (await fetch(`${API}/api/messages`, auth)).json();
  if (list.length) {
    clearInterval(timer);
    const msg = await (await fetch(`${API}/api/messages/${list[0].id}`, auth)).json();
    console.log(msg.subject, "\n", msg.text);
  }
}, 5000);