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.

How it works

Create a temporary email address with the Create Email endpoint — you get a random address on one of our domains.
Use this email address on any website — sign-ups, verifications, downloads, trials.
The website sends an email to that address; our mail server receives and stores it.
Fetch the message list with the Get Messages endpoint, whenever you want.
Read a single message with Get Message, or download its attachments.
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 Admin → Settings → API.

How to get a key: API access is issued per project. Contact us at support@tempmail.pw with what you are building and we will issue you a key.

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

Rate Limiting

The API does not currently publish rate limits or send rate-limit headers. Use it reasonably — poll for new messages every few seconds at most, not in a tight loop. If limits are added later, they will be documented here.

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 — and the email_token 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": []
  }
}

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.

Parameter	Type	Description
`api_key`	string	Your API key.
`type`	string	One 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 wrong key — 404 "Invalid domain type" — 404 "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.

Parameter	Type	Description
`api_key`	string	Your 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.

Parameter	Type	Description
`api_key`	string	Your API key.
`email`	string	The current email address to replace.
`username`	string	The username for the new address (letters and numbers, 2–30 characters; forbidden names are rejected).
`domain`	string	The domain for the new address — 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 wrong key — 404 "This username is not allowed" — 404 "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.

Parameter	Type	Description
`api_key`	string	Your API key.
`email`	string	The 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 wrong key — 404 "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.

Parameter	Type	Description
`api_key`	string	Your API key.
`email`	string	The 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.

Parameter	Type	Description
`api_key`	string	Your API key.
`message_id`	string	The 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.

Parameter	Type	Description
`api_key`	string	Your API key.
`message_id`	string	The 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 wrong key — 404 "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.

Parameter	Type	Description
`hash_id`	string	The message ID (hash) the attachment belongs to.
`file`	string	The 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/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.

Parameter	Type	Description
`email_token`	string	The `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"
}

Status	Meaning	Typical message
`401`	Unauthorized	`"You are not authorized"` — the API key is wrong or missing.
`404`	Not 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 or a key request? Write to support@tempmail.pw — tell us what you are building and we will help you get started.

API Documentation

Temp Mail PW API

How it works

Base URL

Authentication

Rate Limiting

Basic Usage

1. Create a Temporary Email

2. Get List of Messages

3. Get a Specific Message

Endpoints

Get Domains

Create Email

Update Email

Delete Email

Get Messages

Get Message

Delete Message

Download Attachment

Token to Email

Error Handling

Go Premium. Stay Private.