TempsMail API — Free Disposable Email API

The TempsMail API lets you create a disposable inbox and read incoming mail programmatically. It's free and receive-only. Use it to test signup flows, catch one-time verification codes in automated tests, or build your own throwaway-email tools.

overview

• Free with an account — sign in once to get your personal key (keeps the API abuse-free).
• Receive-only — you can create addresses and read mail. There is no send endpoint, so the API can't be used to send spam.
• Inbox is bound to your IP — a created inbox can only be read from the same IP and client that created it, using a secret token. Other people can't read your inbox.
• JSON over HTTPS.

base url

https://tempsmail.org/api

rate limits & fair use

• 100 requests / minute per IP across the API.
• 30 address creations / minute per IP.
• Exceeding a limit returns 429 Too Many Requests. Back off and retry.
• Please cache addresses and poll no faster than once every few seconds. Abuse (mass creation, scraping) will be blocked.

getting your api key

The API is free, but it needs an account — that keeps it from being abused and gives you your own key:

1. Create a free account and verify your email.
2. Open the API Access page in your dashboard.
3. Copy your personal key. In the examples below it's shown as YOUR_API_KEY.

Reading an inbox also requires the secure_key token returned when you created that inbox, and requests must come from the same IP that created it. Keep your key private — treat it like a password.

1. create a temporary address

Creates a random inbox and returns its address plus a secure_key you'll use to read it.

POST /api/extension/emails/{apiKey}

Example

curl -X POST "https://tempsmail.org/api/extension/emails/YOUR_API_KEY"

Response 200 OK

{
  "status": true,
  "data": {
    "email": "[email protected]",
    "fingerprint": "…",
    "email_token": "…",
    "secure_key": "eyJpdiI6…"   // keep this; required to read the inbox
  }
}

2. read the inbox

Returns the messages for an address. Send the secure_key from step 1 in the x-secret-token header. The request must come from the same IP that created the address.

GET /api/extension/messages/{apiKey}/{email}
Header: x-secret-token: {secure_key}

Example

curl "https://tempsmail.org/api/extension/messages/YOUR_API_KEY/[email protected]" \
  -H "x-secret-token: eyJpdiI6…"

Response 200 OK

{
  "status": true,
  "mailbox": "[email protected]",
  "messages": [
    {
      "id": "b7f3…",
      "from": "GitHub",
      "from_email": "[email protected]",
      "subject": "Your verification code",
      "date": "2026-08-21 15:42:00",
      "content": "<p>Your code is 123456</p>"
    }
  ]
}

An empty inbox returns "messages": []. Poll this endpoint every few seconds to wait for a message.

3. list available domains

Returns the domains you can use for addresses.

GET /api/domains/{apiKey}/all

curl "https://tempsmail.org/api/domains/YOUR_API_KEY/all"

the message object

errors

good to know

• Messages are deleted automatically after a short retention window — read them promptly.
• Disposable inboxes aren't private storage. Don't route sensitive mail (banking, passwords you need long term) through them.
• Questions or need higher limits for a real project? Get in touch.