Temp Mail API for Testing and Automation
Create receive-only temporary email addresses from your code and read incoming messages as JSON. Each address stays in your Tmailor account until you delete it, and the API returns the one-time code it finds in a message.
Last updated: October 2026
- REST and JSON
- SDKs, CLI and MCP server
- 100 free mailboxes a month
- Receive-only, 24-hour messages
export TMAILOR_API_KEY="tmk_live_..."
# returns 201 with email, token, web.reuse_url
curl -s -X POST https://open-api.tmailor.com/v1/mailboxes \
-H "Authorization: Bearer $TMAILOR_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{}'# pip install tmailor-sdk
from tmailor import Client
with Client() as client: # reads TMAILOR_API_KEY
box = client.mailboxes.create()
print(box.email)
# trigger the email, then wait for it
msg = box.wait_for_message(
timeout=120, since=(box.created_at or 0) - 1)
print(msg.subject, msg.otp(), msg.links())// npm install tmailor
import { Client } from "tmailor";
const client = new Client(); // reads TMAILOR_API_KEY
const box = await client.mailboxes.create();
console.log(box.email);
// trigger the email, then wait for it
const msg = await box.waitForMessage({
timeout: 120_000, since: box.createdAt - 1 });
console.log(msg.subject, msg.otp, msg.links);<?php // composer require tmailor/tmailor
use Tmailor\Client;
$client = new Client(); // reads TMAILOR_API_KEY
$box = $client->mailboxes->create();
echo $box->email, "\n";
// trigger the email, then wait for it
$msg = $box->waitForMessage(
timeout: 120, since: $box->createdAt - 1);
echo $msg->subject, ' ', $msg->otp; Create an address, wait for the email, read the code.
Pay per mailbox, not per request
Only creating an address uses your mailbox quota. Listing addresses, checking the inbox and reading or deleting messages do not. Paid plans have no daily or monthly request quota, only a per-minute rate limit.
Example: an OTP test that creates one address and checks the inbox 25 times uses one mailbox.
From API key to inbox in four steps
-
Create an API key
Sign in to the API platform with your tmailor.com account or Google and create a key. On the Free plan, also add the one server IP address that will call the API.
-
Create an address
Send one request to get a random address on a shared domain, or choose a custom name on a domain you own and have verified.
-
Read the messages
List the inbox and read each message as JSON: sender, subject, text, cleaned HTML, and the one-time code and links the API found.
-
Keep it or delete it
Addresses do not expire. Open the same inbox on tmailor.com with its reuse link, or delete the address when your test is done.
Built for repeatable email workflows
Give every test run its own inbox instead of sharing one real mailbox.
Sign-up and OTP tests
Create a fresh address for each sign-up, password reset or one-time code check, then read the code from the response.
CI/CD pipelines
Run end-to-end email checks in your pipeline with the key in an environment variable. Paid plans accept requests from any IP address.
QA and staging
Give testers and staging environments their own addresses and keep real inboxes out of test data.
Addresses on your own domain
Add a domain you own, point its MX record to us and create addresses with custom names that follow the naming rules.
Plans and pricing
Pick the number of mailboxes you need. Your allowance resets every 30 days, on yearly plans too.
Free
Try the API and run small projects.
$0 /month
$0 /month
- 100 mailboxes every 30 days
- Up to 30 requests per minute
- 2,000 requests per day
- Calls from one allowlisted IP
- Shared domains and your own domains
Starter
For a developer or a small test suite.
$9 /month
$90 /year
- 3,000 mailboxes every 30 days
- Up to 300 requests per minute
- No daily or monthly request quota
- Calls from any IP address
- Shared domains and your own domains
Pro
For teams that run tests every day.
$29 /month
$290 /year
- 30,000 mailboxes every 30 days
- Up to 600 requests per minute
- No daily or monthly request quota
- Calls from any IP address
- Shared domains and your own domains
Business
For companies with heavy daily automation.
$99 /month
$990 /year
- 150,000 mailboxes every 30 days
- Up to 2,000 requests per minute
- No daily or monthly request quota
- Calls from any IP address
- Shared domains and your own domains
Scale
For large test fleets and busy pipelines.
$199 /month
$1,990 /year
- 400,000 mailboxes every 30 days
- Up to 4,000 requests per minute
- No daily or monthly request quota
- Calls from any IP address
- Shared domains and your own domains
Enterprise
For the highest mailbox volume and request rate.
$499 /month
$4,990 /year
- 2,000,000 mailboxes every 30 days
- Up to 6,000 requests per minute
- No daily or monthly request quota
- Calls from any IP address
- Shared domains and your own domains
Compare plans
These limits change from plan to plan. Everything else is the same on every plan.
| Plan | Free | Starter | Pro | Business | Scale | Enterprise |
|---|---|---|---|---|---|---|
| Monthly price | $0 | $9 | $29 | $99 | $199 | $499 |
| Yearly price | $0 | $90 | $290 | $990 | $1,990 | $4,990 |
| Mailboxes every 30 days | 100 | 3,000 | 30,000 | 150,000 | 400,000 | 2,000,000 |
| Requests per minute | 30 | 300 | 600 | 2,000 | 4,000 | 6,000 |
| Daily request cap | 2,000 | No cap | No cap | No cap | No cap | No cap |
| IP allowlist | Required, 1 IP | Not needed | Not needed | Not needed | Not needed | Not needed |
| Hosted MCP server | Local server only | Included | Included | Included | Included | Included |
Swipe sideways to compare all plans.
Included in every plan
- REST API with JSON responses
- Random addresses on shared domains
- Custom names on your own verified domains
- Unlimited own domains (up to 3 can wait for verification at once)
- Addresses that do not expire
- No limit on how many addresses you keep
- Messages are kept for 24 hours
- One-time code and link extraction (best effort)
- A reuse link to open the inbox on tmailor.com
- Official SDKs and a command-line tool
- Plans can be combined and their limits add up
- Receive-only, without attachments
- Deleting an address does not return quota
- When the mailbox allowance is used up, new addresses cannot be created until the next cycle or an upgrade. Existing inboxes keep working.
- Payments are non-refundable under the API terms. Test your integration on the Free plan first.
Official SDKs and CLI
Call the API from your own language with typed models, automatic retries and a helper that waits for the next message. Every SDK follows the same API and shared test scenarios.
MCP server for AI agents
Let Claude, Cursor, VS Code Copilot and other MCP clients test sign-up flows you own or are allowed to test: the agent creates a real, receive-only address, waits for the email and reads the one-time code or verification link.
Both options give the agent the same tools: create an address, wait for the email and get its one-time code and links, read messages, delete addresses and check your quota. The agent only sees email addresses, never the tokens behind them, and it uses the same mailbox quota and rate limit as the API.
Hosted server
Nothing to installhttps://mcp.tmailor.com/mcp
Add the server URL to your AI app. Apps that support sign-in, such as Claude, ChatGPT and Codex, send you to the Tmailor platform to approve access. Other clients send your API key in the Authorization header.
Needs an active paid plan. Calls come from our server, so you do not need an IP allowlist.
# Claude: add a custom connector with this URL,
# then approve access on the Tmailor platform
https://mcp.tmailor.com/mcp
# Claude Code, with your API key
claude mcp add --transport http tmailor \
https://mcp.tmailor.com/mcp \
--header "Authorization: Bearer tmk_live_..."
# Codex CLI, with your API key
export TMAILOR_API_KEY=tmk_live_...
codex mcp add tmailor \
--url https://mcp.tmailor.com/mcp \
--bearer-token-env-var TMAILOR_API_KEY
# Cursor (~/.cursor/mcp.json)
{"mcpServers": {"tmailor": {
"url": "https://mcp.tmailor.com/mcp",
"headers": {"Authorization": "Bearer tmk_live_..."}}}} See connected apps on the AI connections page and disconnect any of them. A disconnected app loses access within 30 seconds.
Local server
Every plan, including Freetmailor-mcp
It runs on your computer, reads your key from TMAILOR_API_KEY and needs uv or Python 3.10+. On the Free plan, allowlist the IP of that computer.
# Claude Code claude mcp add tmailor \ -e TMAILOR_API_KEY=tmk_live_... \ -- uvx tmailor-mcp # Claude Desktop, Cursor, VS Code # command: uvx args: ["tmailor-mcp"] # without uv pip install tmailor-mcp
Try asking: "Create a temp email, sign up on my staging site with it and tell me the verification code."
Temp mail API FAQ
What counts as a mailbox?
Each new address you create uses one mailbox from the allowance of the current 30-day cycle. Listing, reading and deleting do not use mailboxes, and deleting an address does not give the mailbox back.
Do the addresses expire?
No. An address stays in your account until you delete it. Messages in it are kept for 24 hours.
Can I send email or receive attachments?
No. The API is receive-only and attachments are not delivered.
Can I choose the address name and domain?
On our shared domains the name is random. To choose the name, add and verify a domain you own on the API platform by pointing its MX record to us, then create addresses with a custom name that follows the naming rules.
Do I need an IP allowlist?
Only on the Free plan, where you add the one IP address your server calls from. An IP address can belong to only one Free account, so a shared office or VPN address may already be in use. With an active paid plan, the API accepts requests from any IP address.
Does the API read the verification code for me?
Yes, on a best-effort basis. When you read a message, the response includes the one-time code it found (or null when it is not sure), other code-like values and the links. Always check the value in your test.
Can AI agents such as Claude or ChatGPT use the API?
Yes, through MCP. On a paid plan, add the hosted server https://mcp.tmailor.com/mcp to your AI app and approve access, or send your API key. On any plan, you can run the open-source tmailor-mcp server on your own computer. Either way, the agent can create an address, wait for the email and read the one-time code, using the same mailbox quota as the API.
Is there a request limit on paid plans?
Paid plans have no daily or monthly request quota, but each plan has a per-minute rate limit. The Free plan also has a daily request cap.
Do I need a credit card to start?
No. Sign in with your tmailor.com account or Google, create a key and start on the Free plan. You only pay when you choose a paid plan.
How can I pay for a plan?
Pay with USDT on the TRC20 (Tron) or BEP20 (BNB Smart Chain) network, or with Binance Pay. Credit and debit cards are not accepted. Your plan becomes active when the payment is confirmed, usually within a few minutes.
Can I get a refund?
No. Payments are non-refundable, so test your integration on the Free plan before you upgrade.
What is the API not allowed for?
Spam, fraud, creating accounts in bulk on other services, and evading their bans or limits break the API terms. We may revoke the API keys of accounts that do this and lock them.
Create your first address in minutes
Start on the Free plan with 100 mailboxes a month. No credit card required.