Plus & ProAPI v1

API Documentation

Read messages from your private addresses programmatically, extract verification codes, and long-poll for incoming mail — ideal for automated signup and OTP flows. Available on Plus and Pro plans.

● Base URL: https://api.temp-mail-now.com⚡ Plus: 10 req/min · Pro: 100 req/min

Authentication

Generate an API key from your Dashboard. Pass it as a Bearer token on every request.

Authorization: Bearer tmn_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Keys start with tmn_. Keep them secret — they grant full read access to your messages.

Endpoints

GET/v1/messages

List recent messages across all your private addresses, newest first.

Query parameters

addressstringFilter to a specific address you own. Omit to get all.

limitintegerMax results to return. Default 50, max 200.

curl "https://api.temp-mail-now.com/v1/messages?limit=10" \
  -H "Authorization: Bearer tmn_xxx"

{
  "messages": [
    {
      "id": "uuid",
      "address": "[email protected]",
      "from_address": "[email protected]",
      "from_name": "Alice",
      "subject": "Hello",
      "received_at": "2026-06-01T12:00:00Z",
      "is_spam": false
    }
  ]
}

GET/v1/messages/{id}

Get the full content of a single message, including body text and HTML.

idstring *The message UUID from the list endpoint.

curl "https://api.temp-mail-now.com/v1/messages/MESSAGE_ID" \
  -H "Authorization: Bearer tmn_xxx"

{
  "message": {
    "id": "uuid",
    "address": "[email protected]",
    "from_address": "[email protected]",
    "from_name": "Alice",
    "subject": "Hello",
    "text_body": "Hello world",
    "html_body": "<p>Hello world</p>",
    "attachments": [],
    "received_at": "2026-06-01T12:00:00Z",
    "is_spam": false
  },
  "otp": "483920",
  "otp_candidates": ["483920"]
}

Responses include otp — the best-guess verification code extracted from the message (may be null).

GET/v1/messages/{id}/otp

Extract just the one-time / verification code from a message — no need to parse the body yourself.

idstring *The message UUID.

curl "https://api.temp-mail-now.com/v1/messages/MESSAGE_ID/otp" \
  -H "Authorization: Bearer tmn_xxx"

{
  "id": "uuid",
  "otp": "483920",
  "candidates": ["483920", "10"]
}

otp is the highest-confidence code (keyword-adjacent codes rank first); candidates lists other numbers found. otp is null if none is detected.

GET/v1/messages/wait

Long-poll for the next message to arrive at an owned address — ideal for automated signup/verification flows. Blocks until a message arrives or the timeout elapses.

Query parameters

addressstring *A private address you own to watch for new mail.

timeoutintegerSeconds to wait, 1–60. Default 25.

sinceISO 8601Only return messages after this instant. Default: the moment of the call (waits for genuinely new mail).

curl "https://api.temp-mail-now.com/v1/messages/[email protected]&timeout=30" \
  -H "Authorization: Bearer tmn_xxx"

{
  "message": {
    "id": "uuid",
    "address": "[email protected]",
    "from_address": "[email protected]",
    "subject": "Your verification code",
    "received_at": "2026-06-01T12:00:05Z",
    "is_spam": false
  },
  "otp": "483920",
  "otp_candidates": ["483920"]
}

If no message arrives within timeout, returns { "message": null, "timed_out": true } with HTTP 200 — just call again to keep waiting. Counts as one request against your rate limit.

Rate limits

Plus plan

10 req/min

Pro plan

100 req/min

Rate limit headers are returned on every response:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 97

When exceeded, the API returns HTTP 429:

{
  "error": {
    "code": "rate_limited",
    "message": "Rate limit exceeded (100 req/min for pro plan)"
  }
}

Error responses

All errors use a consistent envelope:

{ "error": { "code": "error_code", "message": "Human-readable message" } }

Status	Code	Meaning
401	missing_key	No Authorization header
401	invalid_key	Key doesn't match any account
403	not_owned	Address not registered under your account
404	not_found	Message ID doesn't exist or isn't yours
429	rate_limited	Too many requests — slow down

Ready to start?

Generate your API key from the Dashboard.

Dashboard →View plans