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@namesgeneratorhub.com","token":"SIGNED_MAILBOX_TOKEN"}

# 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 bound to the exact mailbox address. It has no time-based expiry, although rotating the signing secret or removing a mailbox domain invalidates it; the mail it can read still expires (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 full address 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 ["namesgeneratorhub.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":"namesgeneratorhub.com"}'
→ 200 {"address":"my-alias@namesgeneratorhub.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 address. Multiple valid tokens for the same address share that limit. 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);