API Documentation

Temp Mail PW API

This API lets you create temporary email addresses and manage their messages from your own app, script or service. Create an address, use it anywhere on the web, then fetch the messages it receives. No browser needed.

10 endpoints GET + POST JSON responses No SDK needed
On this page

How it works

  1. Create a temporary email address with the Create Email endpoint. You get a random address on one of our domains.
  2. Use this email address on any website: sign-ups, verifications, downloads, trials.
  3. The website sends an email to that address; our mail server receives and stores it.
  4. Fetch the message list with the Get Messages endpoint, whenever you want.
  5. Read a single message with Get Message, or download its attachments.
  6. Delete the address or a message when you are done. Addresses also expire on their own.

Base URL

All API endpoints live under this base URL. Use https. Plain http is not supported.

https://tempmail.pw/api

One endpoint is different: Token to Email lives on the main domain, not under /api. It is a browser link, not a JSON endpoint. See its section below.

Authentication

Every API endpoint requires your API key. Unlike many APIs, the key is not sent in a header. It is part of the URL path, as the first segment after /api. Replace YOUR_API_KEY in every example with your own key.

curl https://tempmail.pw/api/domains/YOUR_API_KEY/all

Keep your key secret. Anyone with the key can create and delete addresses and read messages on your behalf. Never put it in client-side JavaScript, a public repo, or a URL you share. If a key leaks, regenerate it from your Dashboard → API Access.

How to get a key: API access is included with paid plans (Basic and Pro). Create your own key from your Dashboard → API Access. There is no need to contact support.

If the key is wrong or missing, the API answers 401 Unauthorized with {"status": false, "message": "You are not authorized"}.

Rate Limiting

Each API key has a monthly request limit. Basic allows 500 requests per month, Pro allows 1,000. You can raise the limit from your Dashboard → API Access (extra requests are billed per month). When the monthly limit is reached, the API answers 429 with {"status": false, "message": "Monthly API request limit reached"}. Use it reasonably. Poll for new messages every few seconds at most, not in a tight loop.

Basic Usage

A typical flow: create an address, then poll its inbox for the message you are waiting for.

1. Create a Temporary Email

curl -X POST https://tempmail.pw/api/emails/YOUR_API_KEY

Response:

{
  "status": true,
  "data": {
    "id": 1,
    "email": "kprmen67@sapnadna.space",
    "domain": "sapnadna.space",
    "expire_at": "2026-11-12 21:40:00",
    "created_at": "2026-11-12T21:30:00.000000Z",
    "email_token": "eyJpdiI6..."
  }
}

Save the email. Save the email_token too if you want to open the same inbox in a browser later (see Token to Email).

2. Get List of Messages

curl https://tempmail.pw/api/messages/YOUR_API_KEY/kprmen67@sapnadna.space

Response:

{
  "status": true,
  "mailbox": "kprmen67@sapnadna.space",
  "email_token": "eyJpdiI6...",
  "messages": [
    {
      "id": "a48b927e...",
      "subject": "Welcome!",
      "from": "Service",
      "from_email": "no-reply@service.com",
      "to": "kprmen67@sapnadna.space",
      "receivedAt": "2026-11-12 21:31:00",
      "is_seen": false,
      "html": true,
      "content": "<p>Welcome to our service!</p>",
      "attachments": []
    }
  ]
}

3. Get a Specific Message

curl https://tempmail.pw/api/messages/YOUR_API_KEY/message/a48b927e...

Response:

{
  "status": true,
  "data": {
    "id": "a48b927e...",
    "subject": "Welcome!",
    "from": "Service",
    "from_email": "no-reply@service.com",
    "to": "kprmen67@sapnadna.space",
    "receivedAt": "2026-11-12 21:31:00",
    "is_seen": true,
    "html": true,
    "content": "<p>Welcome to our service!</p>",
    "attachments": []
  }
}

4. Check if an Email is Disposable

Before you accept a signup, check whether the address is disposable. If disposable is true, reject it before it reaches your database.

curl https://tempmail.pw/api/disposable/YOUR_API_KEY/user@mailinator.com

Response:

{
  "status": true,
  "data": {
    "status": true,
    "email": "user@mailinator.com",
    "domain": "mailinator.com",
    "disposable": true,
    "free": false,
    "mx_found": true,
    "mx_hosts": ["mail.mailinator.com"],
    "verdict": "disposable"
  }
}

Block the signup when the verdict is disposable. See the full Check Disposable Email endpoint, or try it in the browser on the Disposable Email Checker page.

Endpoints

GET/api/domains/{api_key}/{type}

Get Domains

Retrieve a list of all available mail domains, filtered by type. Use this to let your users pick a domain before creating an address. Guest domains are open to everyone. No account needed. Free domains are for registered users, and Premium domains need a paid plan.

ParameterTypeDescription
api_keystringYour API key.
typestringOne of guest, free, premium or all. Anything else returns 404.

Example Request

curl https://tempmail.pw/api/domains/YOUR_API_KEY/all

Example Response

{
  "status": true,
  "data": {
    "domains": [
      { "domain": "aiopenapi.space", "type": "Free" },
      { "domain": "mecasa.space", "type": "Free" },
      { "domain": "aiseed.site", "type": "Premium" }
    ]
  }
}

Errors: 401 means the key is wrong. 404 means the domain type is not valid ("Invalid domain type") or no domains were found for that type ("No domains found for the selected type").

POST/api/emails/{api_key}

Create Email

Create a new temporary email address. The address is generated for you. You do not send an email or a name in the request body. Send an empty POST to the endpoint.

ParameterTypeDescription
api_keystringYour API key.

Example Request

curl -X POST https://tempmail.pw/api/emails/YOUR_API_KEY

Example Response

{
  "status": true,
  "data": {
    "id": 1,
    "email": "kprmen67@sapnadna.space",
    "domain": "sapnadna.space",
    "ip": "203.0.113.10",
    "fingerprint": "5d41402abc4b2a76b9719d911017c592",
    "expire_at": "2026-11-12 21:40:00",
    "created_at": "2026-11-12T21:30:00.000000Z",
    "email_token": "eyJpdiI6..."
  }
}

Notes: the address expires 10 minutes after creation (expire_at). Keep the email_token. It opens the same inbox in a browser via Token to Email.

POST/api/emails/{api_key}/{email}/{username}/{domain}

Update Email

Replace an existing temporary email address with a new one you choose. The old address is expired immediately and a new address, username@domain, is created. The username and domain are part of the URL. There is no request body.

ParameterTypeDescription
api_keystringYour API key.
emailstringThe current email address to replace.
usernamestringThe username for the new address (letters and numbers, 2 to 30 characters; forbidden names are rejected).
domainstringThe domain for the new address. It must be one of the domains from Get Domains.

Example Request

curl -X POST https://tempmail.pw/api/emails/YOUR_API_KEY/kprmen67@sapnadna.space/myname/sapnadna.space

Example Response

{
  "status": true,
  "data": {
    "id": 2,
    "email": "myname@sapnadna.space",
    "domain": "sapnadna.space",
    "expire_at": "2026-11-12 21:40:00",
    "created_at": "2026-11-12T21:30:00.000000Z"
  }
}

Errors: 401 means the key is wrong. 404 means the username is not allowed ("This username is not allowed") or the domain is not allowed ("This domain is not allowed").

POST/api/emails/{api_key}/{email}

Delete Email

Delete a temporary email address and its messages. Note the method is POST, not DELETE.

ParameterTypeDescription
api_keystringYour API key.
emailstringThe email address to delete.

Example Request

curl -X POST https://tempmail.pw/api/emails/YOUR_API_KEY/kprmen67@sapnadna.space

Example Response

{
  "status": true,
  "message": "Email has been successfully deleted."
}

Errors: 401 means the key is wrong. 404 means the email was not found ("Email not found.").

GET/api/messages/{api_key}/{email}

Get Messages

Retrieve all messages for a specific email address. Poll this endpoint to wait for a verification code or a reply.

ParameterTypeDescription
api_keystringYour API key.
emailstringThe email address to retrieve messages for.

Example Request

curl https://tempmail.pw/api/messages/YOUR_API_KEY/kprmen67@sapnadna.space

Example Response

{
  "status": true,
  "mailbox": "kprmen67@sapnadna.space",
  "email_token": "eyJpdiI6...",
  "messages": [
    {
      "id": "a48b927e...",
      "is_seen": false,
      "subject": "Hello!",
      "from": "Sender Name",
      "from_email": "sender@example.com",
      "to": "kprmen67@sapnadna.space",
      "receivedAt": "2026-11-12 21:31:00",
      "html": true,
      "content": "<p>This is a test message.</p>",
      "attachments": [
        {
          "name": "file.pdf",
          "extension": "pdf",
          "size": 1024,
          "url": "https://tempmail.pw/api/d/a48b927e.../file.pdf"
        }
      ]
    }
  ]
}

Notes: id is the message hash. Use it with Get Message, Delete Message and Download Attachment. content is the full HTML (or plain text) body. Each attachment has a ready-to-use url. An empty inbox returns "messages": [].

GET/api/messages/{api_key}/message/{message_id}

Get Message

Retrieve a single message by its ID (the id from Get Messages). Reading a message marks it as seen.

ParameterTypeDescription
api_keystringYour API key.
message_idstringThe ID (hash) of the message to retrieve.

Example Request

curl https://tempmail.pw/api/messages/YOUR_API_KEY/message/a48b927e...

Example Response

{
  "status": true,
  "data": {
    "id": "a48b927e...",
    "is_seen": true,
    "subject": "Hello!",
    "from": "Sender Name",
    "from_email": "sender@example.com",
    "to": "kprmen67@sapnadna.space",
    "receivedAt": "2026-11-12 21:31:00",
    "html": true,
    "content": "<p>This is a test message.</p>",
    "attachments": []
  }
}
POST/api/messages/{api_key}/message/{message_id}

Delete Message

Delete a single message by its ID. Note the method is POST, not DELETE.

ParameterTypeDescription
api_keystringYour API key.
message_idstringThe ID (hash) of the message to delete.

Example Request

curl -X POST https://tempmail.pw/api/messages/YOUR_API_KEY/message/a48b927e...

Example Response

{
  "status": true,
  "message": "Message was deleted successfully."
}

Errors: 401 means the key is wrong. 404 means the message was not found ("Message not found.").

GET/api/d/{hash_id}/{file}

Download Attachment

Download an attachment from a message. This endpoint takes no API key. The hash_id is the message ID and file is the attachment name. In practice you never build this URL yourself: every attachment in a Get Messages / Get Message response already has a ready-to-use url field pointing here.

ParameterTypeDescription
hash_idstringThe message ID (hash) the attachment belongs to.
filestringThe attachment file name, e.g. file.pdf.

Example Request

curl https://tempmail.pw/api/d/a48b927e.../file.pdf --output file.pdf

Example Response

The file is downloaded as an attachment. A missing file returns 404.
GET/api/disposable/{api_key}/{email}

Check Disposable Email

Check whether an email address (or just a domain) belongs to a known disposable or temporary email service. The check compares the domain with a list of more than 220,000 known disposable domains, a separate list of free webmail providers, and a live MX lookup. Use it at signup to reject throwaway addresses before they reach your database. Try it in the browser on the Disposable Email Checker page.

ParameterTypeDescription
api_keystringYour API key.
emailstringThe email address to check, or just a domain.

Example Request

curl https://tempmail.pw/api/disposable/YOUR_API_KEY/test@mailinator.com

Example Response

{
  "status": true,
  "data": {
    "status": true,
    "email": "test@mailinator.com",
    "domain": "mailinator.com",
    "disposable": true,
    "free": false,
    "mx_found": true,
    "mx_hosts": ["mail.mailinator.com"],
    "verdict": "disposable"
  }
}

Verdicts: disposable means the address is on the disposable list. clean means it is not disposable and the mail servers answer. free means a free webmail provider, not a throwaway. no_mx means the domain has no mail servers. unknown_mx means the mail servers could not be reached. invalid means the email or domain is not valid. Each call counts toward your key's monthly API limit.

Errors: 401 means the key is wrong. 429 means the monthly limit is reached. An invalid email or domain returns 200 with status: false and verdict: "invalid".

GET/token/{email_token}

Token to Email

Send your visitors to a page where the email behind a token is created or displayed. This is a browser link, not a JSON endpoint. Open it in a browser. Do not call it with curl. It is how the QR code on the home page works: scanning it opens the same inbox.

ParameterTypeDescription
email_tokenstringThe email_token from Create Email or Get Messages.

Example Link

https://tempmail.pw/token/eyJpdiI6...

The same link also works as https://tempmail.pw/go-to-email/{email_token}. The visitor lands on the site with that temporary inbox open.

Error Handling

The API uses standard HTTP status codes. Errors are returned as JSON with status: false and a human-readable message:

{
  "status": false,
  "message": "You are not authorized"
}
StatusMeaningTypical message
401Unauthorized"You are not authorized". The API key is wrong or missing.
404Not found"Invalid domain type", "No domains found for the selected type", "This username is not allowed", "This domain is not allowed", "Email not found.", "Message not found.", or a missing attachment file.

Get Messages has its own error shape: on a mail-server problem it still returns 200 with {"status": false, "mailbox": "Unable to retrieve emails at this time. Please try Again", "messages": []}. Check status in the body, not just the HTTP code.

Questions? Write to support@tempmail.pw. Tell us what you are building and we will help you get started.

Nâng cấp Premium. Giữ riêng tư.

Tên miền tùy chỉnh & cao cấp và API đầy đủ, được xây dựng cho những người coi trọng quyền riêng tư.

Register Now
Temp Mail trên laptop và ứng dụng di động