Authentication

All API v1 endpoints authenticate using your API key passed directly in the URL path as the {apiKey} segment.

You can find your API key in the Dashboard → API page. Keep it secret — anyone with your key can act on your behalf.

Example:

curl https://temp-mail.plus/api/v1/history/{your-api-key}

Quick Start

Here's a typical workflow showing how to create a temporary email, wait for messages, read them, and clean up.

Create a temporary email

Generate a random disposable address with a single POST request.
```
curl -X POST https://temp-mail.plus/api/v1/email/create/{your-api-key}
```
Use the email address

Sign up on a website, trigger a verification email, or use the address wherever you need a temporary inbox. Save the email_token from the response.
Check for new messages

Poll the messages endpoint to see incoming mail.
```
curl https://temp-mail.plus/api/v1/messages/{email_token}/{your-api-key}
```
Read a specific message

Fetch the full message content using its id from the messages list.
```
curl https://temp-mail.plus/api/v1/message/{message_id}/{your-api-key}
```
Download attachments (optional)

If the message has attachments, download them using the attachment URL returned in the message response.
```
curl -O https://temp-mail.plus/api/v1/d/{hash_id}/file.pdf/{your-api-key}
```

Clean up

Delete individual messages or the entire email when you're done.

# Delete a message
curl -X POST https://temp-mail.plus/api/v1/message/delete/{message_id}/{your-api-key}

# Delete the email
curl -X POST https://temp-mail.plus/api/v1/email/delete/{email_token}/{your-api-key}

Rate Limits

API requests are rate-limited per plan. Exceeding the limit returns a 429 status.

Plan	Requests / min	API Calls / month
Free	10	50
Basic	30	1,000
Pro	60	10,000

Every API response includes rate-limit headers so you can track your usage:

Response Headers

X-RateLimit-Limit — Maximum requests allowed per window
X-RateLimit-Remaining — Requests remaining in current window
X-RateLimit-Reset — Unix timestamp when the current window resets
Retry-After — Seconds until you can retry (only on 429 responses)

You can also check your rate limit status programmatically via the Rate Limit endpoint without consuming any API usage.

When you exceed the limit, you'll receive a 429 response with Retry-After header:

{
  "message": "Too Many Attempts.",
  "retry_after": 42
}

Error Handling

All errors return a consistent JSON envelope:

{
  "status": "error",
  "message": "Human-readable error description."
}

Code	Meaning	Common Cause
400	Bad Request	Invalid email format or parameters
401	Unauthorized	Invalid or missing API key
404	Not Found	Resource doesn't exist or domain not allowed
429	Too Many Requests	Rate limit or monthly quota exceeded

POST /email/create/{apiKey}

Create a new temporary email address. By default a random address is generated, but you can customize the email, domain, or domain type via the JSON request body.

Parameter	Type	Description
`apiKey` required	string	Your API key (URL path)

Request Body (JSON, optional)

Field	Type	Description
`email` optional	string	Desired username (before the @). Must be used with `domain`.
`domain` optional	string	Domain to use (must be an allowed domain for your plan). If only `domain` is provided, a random username is generated.
`domain_type` optional	string	Filter domain by type: `free`, `premium`, or `custom`. Ignored if `domain` is provided.

# Random email (no body needed)
curl -X POST https://temp-mail.plus/api/v1/email/create/{your-api-key}

# Custom email + domain
curl -X POST https://temp-mail.plus/api/v1/email/create/{your-api-key} \
  -H "Content-Type: application/json" \
  -d '{"email": "myname", "domain": "domain.com"}'

# Random email on a specific domain
curl -X POST https://temp-mail.plus/api/v1/email/create/{your-api-key} \
  -H "Content-Type: application/json" \
  -d '{"domain": "domain.com"}'

# Random email on free domains only
curl -X POST https://temp-mail.plus/api/v1/email/create/{your-api-key} \
  -H "Content-Type: application/json" \
  -d '{"domain_type": "free"}'

import requests

# Random email
response = requests.post(
    "https://temp-mail.plus/api/v1/email/create/{your-api-key}"
)

# Custom email + domain
response = requests.post(
    "https://temp-mail.plus/api/v1/email/create/{your-api-key}",
    json={"email": "myname", "domain": "domain.com"}
)
print(response.json())

// Random email
const response = await fetch(
  "https://temp-mail.plus/api/v1/email/create/{your-api-key}",
  { method: "POST" }
);

// Custom email + domain
const response = await fetch(
  "https://temp-mail.plus/api/v1/email/create/{your-api-key}",
  {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({ email: "myname", domain: "domain.com" })
  }
);
const data = await response.json();
console.log(data);

// Random email
$response = Http::post(
    "https://temp-mail.plus/api/v1/email/create/{your-api-key}"
);

// Custom email + domain
$response = Http::post(
    "https://temp-mail.plus/api/v1/email/create/{your-api-key}",
    ['email' => 'myname', 'domain' => 'domain.com']
);
$data = $response->json();

Response 200

{
  "status": "success",
  "data": {
    "id": 1,
    "email": "[email protected]",
    "domain": "domain.com",
    "ip": "203.0.113.1",
    "fingerprint": "a1b2c3d4...",
    "expire_at": "2025-01-15T12:00:00.000000Z",
    "email_token": "eyJpdiI6...",
    "ttl": 600
  }
}

Response Headers

X-RateLimit-Limit — e.g. 60
X-RateLimit-Remaining — e.g. 59
X-RateLimit-Reset — e.g. 1705312800

400 {"status":"error","message":"This username is not allowed"}

400 {"status":"error","message":"This domain is not allowed"}

400 {"status":"error","message":"Invalid domain_type. Use: free, premium, or custom."}

401 {"status":"error","message":"Unauthorized access. Invalid API key."}

429 {"status":"error","message":"API usage limit reached."}

Delete Email

POST /email/delete/{email_token}/{apiKey}

Delete a temporary email address. The email is expired and soft-deleted immediately along with all its messages.

Parameter	Type	Description
`email_token` required	string	Encrypted token from create response
`apiKey` required	string	Your API key

curl -X POST https://temp-mail.plus/api/v1/email/delete/{email_token}/{your-api-key}

import requests

response = requests.post(
    f"https://temp-mail.plus/api/v1/email/delete/{email_token}/{api_key}"
)
print(response.json())

const response = await fetch(
  `https://temp-mail.plus/api/v1/email/delete/${emailToken}/${apiKey}`,
  { method: "POST" }
);
const data = await response.json();
console.log(data);

$response = Http::post(
    "https://temp-mail.plus/api/v1/email/delete/{$emailToken}/{$apiKey}"
);
$data = $response->json();

Response 200

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

Response Headers

X-RateLimit-Limit — e.g. 60
X-RateLimit-Remaining — e.g. 58
X-RateLimit-Reset — e.g. 1705312800

400 {"status":"error","message":"Invalid email format"}

401 {"status":"error","message":"Unauthorized access. Invalid API key."}

404 {"status":"error","message":"Email not found."}

429 {"status":"error","message":"API usage limit reached."}

Create Email Reopen Email

GET /api/go-to-email/{email_token}/{apiKey}

Reopen a previously used email by its token. Creates a new inbox entry for the same address, allowing you to receive messages again.

Parameter	Type	Description
`email_token` required	string	Encrypted token of the email to reopen
`apiKey` required	string	Your API key

curl https://temp-mail.plus/api/v1/api/go-to-email/{email_token}/{your-api-key}

import requests

response = requests.get(
    f"https://temp-mail.plus/api/v1/api/go-to-email/{email_token}/{api_key}"
)
print(response.json())

const response = await fetch(
  `https://temp-mail.plus/api/v1/api/go-to-email/${emailToken}/${apiKey}`
);
const data = await response.json();
console.log(data);

$response = Http::get(
    "https://temp-mail.plus/api/v1/api/go-to-email/{$emailToken}/{$apiKey}"
);
$data = $response->json();

Response 200

{
  "status": "success",
  "data": {
    "id": 3,
    "email": "[email protected]",
    "domain": "domain.com",
    "ip": "203.0.113.1",
    "fingerprint": "a1b2c3d4...",
    "expire_at": "2025-01-15T12:00:00.000000Z",
    "email_token": "eyJpdiI6...",
    "ttl": 600
  }
}

Response Headers

X-RateLimit-Limit — e.g. 60
X-RateLimit-Remaining — e.g. 57
X-RateLimit-Reset — e.g. 1705312800

400 {"status":"error","message":"Invalid email format"}

401 {"status":"error","message":"Unauthorized access. Invalid API key."}

404 {"status":"error","message":"This domain is not allowed"}

429 {"status":"error","message":"API usage limit reached."}

Delete Email List Messages

GET /messages/{email_token}/{apiKey}

Retrieve all messages for a temporary email inbox. Returns message metadata including sender, subject, and read status.

Parameter	Type	Description
`email_token` required	string	Encrypted token of the email inbox
`apiKey` required	string	Your API key

curl https://temp-mail.plus/api/v1/messages/{email_token}/{your-api-key}

import requests

response = requests.get(
    f"https://temp-mail.plus/api/v1/messages/{email_token}/{api_key}"
)
print(response.json())

const response = await fetch(
  `https://temp-mail.plus/api/v1/messages/${emailToken}/${apiKey}`
);
const data = await response.json();
console.log(data);

$response = Http::get(
    "https://temp-mail.plus/api/v1/messages/{$emailToken}/{$apiKey}"
);
$data = $response->json();

Response 200

{
  "status": "success",
  "mailbox": "[email protected]",
  "email_token": "eyJpdiI6...",
  "messages": [
    {
      "id": "abc123",
      "to": "[email protected]",
      "subject": "Welcome!",
      "from": "Sender Name",
      "from_email": "[email protected]",
      "receivedAt": "2025-01-15T10:30:00Z",
      "is_seen": 0,
      "attachments": []
    }
  ]
}

Response Headers

X-RateLimit-Limit — e.g. 60
X-RateLimit-Remaining — e.g. 56
X-RateLimit-Reset — e.g. 1705312800

400 {"status":"error","message":"Invalid email format"}

401 {"status":"error","message":"Unauthorized access. Invalid API key."}

429 {"status":"error","message":"API usage limit reached."}

Reopen Email Get Message

GET /message/{message_id}/{apiKey}

Retrieve a single message by its ID (hash_id). Returns full message content including HTML body and attachments.

Parameter	Type	Description
`message_id` required	string	Message hash ID from the messages list
`apiKey` required	string	Your API key

curl https://temp-mail.plus/api/v1/message/{message_id}/{your-api-key}

import requests

response = requests.get(
    f"https://temp-mail.plus/api/v1/message/{message_id}/{api_key}"
)
print(response.json())

const response = await fetch(
  `https://temp-mail.plus/api/v1/message/${messageId}/${apiKey}`
);
const data = await response.json();
console.log(data);

$response = Http::get(
    "https://temp-mail.plus/api/v1/message/{$messageId}/{$apiKey}"
);
$data = $response->json();

Response 200

{
  "status": "success",
  "data": {
    "uuid": "abc123-def456",
    "to": "[email protected]",
    "subject": "Welcome!",
    "from": "Sender Name",
    "from_email": "[email protected]",
    "receivedAt": "2025-01-15T10:30:00Z",
    "id": "abc123",
    "attachments": [],
    "content": "<html>...</html>"
  }
}

Response Headers

X-RateLimit-Limit — e.g. 60
X-RateLimit-Remaining — e.g. 54
X-RateLimit-Reset — e.g. 1705312800

401 {"status":"error","message":"Unauthorized access. Invalid API key."}

429 {"status":"error","message":"API usage limit reached."}

List Messages Message Source

GET /message/{message_id}/source/{apiKey}

Retrieve the raw EML source of a message. The EML file contains the complete original email including all headers, MIME parts, and encoded attachments. Useful for debugging, archiving, or advanced email parsing.

Parameter	Type	Description
`message_id` required	string	Message hash ID from the messages list
`apiKey` required	string	Your API key

curl https://temp-mail.plus/api/v1/message/{message_id}/source/{your-api-key}

import requests

response = requests.get(
    f"https://temp-mail.plus/api/v1/message/{message_id}/source/{api_key}"
)
data = response.json()
# Save raw EML to file
with open("message.eml", "w") as f:
    f.write(data["data"]["source"])

const response = await fetch(
  `https://temp-mail.plus/api/v1/message/${messageId}/source/${apiKey}`
);
const data = await response.json();
// data.data.source contains the raw EML
console.log(data.data.source);

$response = Http::get(
    "https://temp-mail.plus/api/v1/message/{$messageId}/source/{$apiKey}"
);
$source = $response->json()['data']['source'];
// Save raw EML
file_put_contents('message.eml', $source);

Response 200

{
  "status": "success",
  "data": {
    "id": "abc123",
    "source": "From: [email protected]\r\nTo: [email protected]\r\nSubject: Hello\r\nMIME-Version: 1.0\r\n..."
  }
}

Response Headers

X-RateLimit-Limit — e.g. 60
X-RateLimit-Remaining — e.g. 54
X-RateLimit-Reset — e.g. 1705312800

401 {"status":"error","message":"Unauthorized access. Invalid API key."}

404 {"status":"error","message":"Message source not available."}

429 {"status":"error","message":"API usage limit reached."}

Get Message Delete Message

POST /message/delete/{message_id}/{apiKey}

Delete a single message by its ID. This action is permanent and cannot be undone.

Parameter	Type	Description
`message_id` required	string	Message hash ID to delete
`apiKey` required	string	Your API key

curl -X POST https://temp-mail.plus/api/v1/message/delete/{message_id}/{your-api-key}

import requests

response = requests.post(
    f"https://temp-mail.plus/api/v1/message/delete/{message_id}/{api_key}"
)
print(response.json())

const response = await fetch(
  `https://temp-mail.plus/api/v1/message/delete/${messageId}/${apiKey}`,
  { method: "POST" }
);
const data = await response.json();
console.log(data);

$response = Http::post(
    "https://temp-mail.plus/api/v1/message/delete/{$messageId}/{$apiKey}"
);
$data = $response->json();

Response 200

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

Response Headers

X-RateLimit-Limit — e.g. 60
X-RateLimit-Remaining — e.g. 53
X-RateLimit-Reset — e.g. 1705312800

401 {"status":"error","message":"Unauthorized access. Invalid API key."}

404 {"status":"error","message":"Message not found."}

429 {"status":"error","message":"API usage limit reached."}

Message Source Download Attachment

GET /d/{hash_id}/{file}/{apiKey}

Download an attachment file from a message. Returns the file binary directly on success. Requires the attachments feature to be enabled on your plan.

Parameter	Type	Description
`hash_id` required	string	Message hash ID containing the attachment
`file` optional	string	Attachment filename
`apiKey` required	string	Your API key

curl -O https://temp-mail.plus/api/v1/d/{hash_id}/document.pdf/{your-api-key}

import requests

response = requests.get(
    f"https://temp-mail.plus/api/v1/d/{hash_id}/document.pdf/{api_key}"
)
with open("document.pdf", "wb") as f:
    f.write(response.content)

const response = await fetch(
  `https://temp-mail.plus/api/v1/d/${hashId}/document.pdf/${apiKey}`
);
const buffer = await response.arrayBuffer();
// Save buffer to file

$response = Http::get(
    "https://temp-mail.plus/api/v1/d/{$hashId}/document.pdf/{$apiKey}"
);
Storage::put('document.pdf', $response->body());

Response 200

# Binary file download (Content-Disposition: attachment)

Response Headers

X-RateLimit-Limit — e.g. 60
X-RateLimit-Remaining — e.g. 52
X-RateLimit-Reset — e.g. 1705312800

401 {"status":"error","message":"Unauthorized access. Invalid API key."}

404 {"status":"error","message":"Not found."}

429 {"status":"error","message":"you can't download the attachments"}

Delete Message Email History

GET /history/{apiKey}

List all previously created temporary email addresses for your account, ordered by most recent first.

Parameter	Type	Description
`apiKey` required	string	Your API key

curl https://temp-mail.plus/api/v1/history/{your-api-key}

import requests

response = requests.get(
    f"https://temp-mail.plus/api/v1/history/{api_key}"
)
print(response.json())

const response = await fetch(
  `https://temp-mail.plus/api/v1/history/${apiKey}`
);
const data = await response.json();
console.log(data);

$response = Http::get(
    "https://temp-mail.plus/api/v1/history/{$apiKey}"
);
$data = $response->json();

Response 200

{
  "status": "success",
  "message": "history fetched successfully",
  "data": [
    {
      "id": 1,
      "email": "[email protected]",
      "created_at": "2025-01-15T08:00:00.000000Z"
    },
    {
      "id": 2,
      "email": "[email protected]",
      "created_at": "2025-01-14T15:30:00.000000Z"
    }
  ]
}

Response Headers

X-RateLimit-Limit — e.g. 60
X-RateLimit-Remaining — e.g. 51
X-RateLimit-Reset — e.g. 1705312800

401 {"status":"error","message":"Unauthorized access. Invalid API key."}

429 {"status":"error","message":"API usage limit reached."}

Download Attachment List Domains

GET /domains/{apiKey}/{type?}

List available domains for creating temporary emails. Filter by type to see only free, premium, or custom domains.

Parameter	Type	Description
`apiKey` required	string	Your API key
`type` optional	string	Filter: `free`, `premium`, `custom`, or `all` (default)

# All domains
curl https://temp-mail.plus/api/v1/domains/{your-api-key}/all

# Only free domains
curl https://temp-mail.plus/api/v1/domains/{your-api-key}/free

import requests

# All domains
response = requests.get(
    f"https://temp-mail.plus/api/v1/domains/{api_key}/all"
)
print(response.json())

// All domains
const response = await fetch(
  `https://temp-mail.plus/api/v1/domains/${apiKey}/all`
);
const data = await response.json();
console.log(data);

// All domains
$response = Http::get(
    "https://temp-mail.plus/api/v1/domains/{$apiKey}/all"
);
$data = $response->json();

Response 200

{
  "status": "success",
  "data": {
    "domains": [
      { "domain": "temp-mail.plus", "type": "Free" },
      { "domain": "premium-mail.com", "type": "Premium" },
      { "domain": "my-domain.com", "type": "Custom" }
    ]
  }
}

Response Headers

X-RateLimit-Limit — e.g. 60
X-RateLimit-Remaining — e.g. 50
X-RateLimit-Reset — e.g. 1705312800

400 {"status":"error","message":"Invalid domain type. Use: free, premium, custom, or all."}

401 {"status":"error","message":"Unauthorized access. Invalid API key."}

429 {"status":"error","message":"API usage limit reached."}

Email History Rate Limit

GET /rate-limit/{apiKey}

Check your current rate limit status without consuming any API usage. This endpoint is excluded from rate limiting and does not count toward your monthly API call quota.

Parameter	Type	Description
`apiKey` required	string	Your API key

curl https://temp-mail.plus/api/v1/rate-limit/{your-api-key}

import requests

response = requests.get(
    f"https://temp-mail.plus/api/v1/rate-limit/{api_key}"
)
print(response.json())

const response = await fetch(
  `https://temp-mail.plus/api/v1/rate-limit/${apiKey}`
);
const data = await response.json();
console.log(data);

$response = Http::get(
    "https://temp-mail.plus/api/v1/rate-limit/{$apiKey}"
);
$data = $response->json();

Response 200

{
  "status": "success",
  "data": {
    "limit": 60,
    "remaining": 45,
    "reset": 32,
    "plan": "pro-plan"
  }
}

Field	Type	Description
`limit`	integer	Maximum requests allowed per minute for your plan
`remaining`	integer	Requests remaining in the current window
`reset`	integer	Seconds until the rate limit window resets
`plan`	string	Your current plan tag (e.g. `free`, `pro`, `pro-plan`)

401 {"status":"error","message":"Unauthorized access. Invalid API key."}

List Domains

API Documentation

API Reference v1

Authentication

Quick Start

Rate Limits

Error Handling

Emails