TempHotmail · API v1
Mailbox API documentation
Create test inboxes and verify delivery from Codex, Claude Code, or your terminal. Included with active Pro monthly and yearly subscriptions.
Connect your AI tools
Codex App
- In Plugins, select + and Add custom MCP server. You can also open Settings, select MCP servers, and choose Add server.
- Name it TempHotmail and paste the server URL below. If the form asks for authentication, choose OAuth and dynamic client registration (DCR). In desktop settings, choose Streamable HTTP.
- Save and select Connect or Authenticate. Sign in to TempHotmail and choose Authorize and return. Select TempHotmail in a new chat or use /mcp to check the connection.
https://temphotmail.com/mcpEach connection can only access its own test inboxes. Revoke a connection from API keys and app connections in your dashboard.
Codex CLI with an API key
Set TEMPHOTMAIL_API_KEY to an AI & CLI key, then add this configuration to ~/.codex/config.toml.
[mcp_servers.temphotmail]
url = "https://temphotmail.com/mcp"
bearer_token_env_var = "TEMPHOTMAIL_API_KEY"
tool_timeout_sec = 30Claude Code
Set TEMPHOTMAIL_API_KEY to an AI & CLI key. Add .mcp.json to your project root, or merge temphotmail into your existing mcpServers. Restart Claude Code and use /mcp to check the connection.
{
"mcpServers": {
"temphotmail": {
"type": "http",
"url": "https://temphotmail.com/mcp",
"headers": {
"Authorization": "Bearer ${TEMPHOTMAIL_API_KEY}"
}
}
}
}Run a delivery test
Create a test inbox and tell me its address. After I send an email with the subject Welcome, verify that it arrived.
Tools include create_mailbox, list_mailboxes, list_messages, read_message, and wait_for_email. Waiting is capped at 20 seconds with exact sender or subject matching. Use read_message to retrieve a body.
Use the terminal and CI
The CLI requires Node.js 22 or newer. Set the same TEMPHOTMAIL_API_KEY environment variable. These install commands are for macOS and Linux. On Windows, download the file and run node temphotmail.mjs.
Download the CLImkdir -p "$HOME/.local/bin"
curl -fsSL https://temphotmail.com/downloads/temphotmail.mjs \
-o "$HOME/.local/bin/temphotmail"
chmod +x "$HOME/.local/bin/temphotmail"
"$HOME/.local/bin/temphotmail" --versionexport PATH="$HOME/.local/bin:$PATH"
temphotmail mailbox create --idempotency-key signup-test-001 --json
# Send your test email to data.email, then replace MAILBOX_ID.
temphotmail mail wait --mailbox MAILBOX_ID --subject "Welcome" --timeout 20 --jsonRun temphotmail --help for all commands. Use --json for machine-readable output. A wait timeout exits with status 3 so CI can distinguish it from a failed request.
REST API quickstart
REST supports both key types. AI & CLI keys can access only mailboxes they created. Account API keys can access all Premium mailboxes in the account. Set TEMPHOTMAIL_API_KEY to the key you choose.
curl -X POST https://temphotmail.com/api/v1/mailboxes \
-H "Authorization: Bearer $TEMPHOTMAIL_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: inbox-test-001" \
-d '{}'Send a test email to data.email from the response. Replace MAILBOX_ID with data.id and list the inbox.
curl "https://temphotmail.com/api/v1/mailboxes/MAILBOX_ID/messages?limit=25" \
-H "Authorization: Bearer $TEMPHOTMAIL_API_KEY"Replace MESSAGE_ID with a message ID from the list to read its body. Sanitize sender-supplied HTML before rendering it.
curl "https://temphotmail.com/api/v1/mailboxes/MAILBOX_ID/messages/MESSAGE_ID" \
-H "Authorization: Bearer $TEMPHOTMAIL_API_KEY"Endpoint reference
Base URL https://temphotmail.com/api/v1
POST /mailboxesCreate a mailbox. Pass optional name and domain fields or send {} for a random address.
GET /mailboxesList the unexpired Premium mailboxes accessible to the key.
GET /mailboxes/{mailboxId}/messagesList newest messages first. The default limit is 25 and the maximum is 50. Pass next_cursor as cursor for the next page. A null cursor marks the final page.
GET /mailboxes/{mailboxId}/messages/waitWait for a message with an AI & CLI key. Filter by subject, from or after, and set timeout_seconds.
GET /mailboxes/{mailboxId}/messages/{messageId}Get a message including its text_body and html_body.
Limits and subscription expiry
- Each account can have up to 25 active mailboxes and five active API keys or OAuth connections combined. The website and API share a limit of 10 creation requests per 10 minutes. API reads share a separate limit of 120 requests per minute.
- Within 24 hours, retrying a creation with the same Idempotency-Key and parameters returns the original result with 200. Account keys share that history by account, and AI & CLI keys each have their own. Creation returns 201, and conflicting parameters return 409.
- After turning off renewal, API access lasts until the end of the paid period. Check expires_at for each mailbox’s expiry.
Handling errors
Errors include error.code, error.message and request_id. Include request_id when contacting support.
- 400 / 413
- Invalid input or request body too large.
- 401 · INVALID_API_KEY
- API key is missing, invalid or revoked.
- 403 · SUBSCRIPTION_REQUIRED
- The account does not have an active Pro subscription.
- 403 · AUTOMATION_KEY_REQUIRED
- This operation requires an AI & CLI key.
- 404 · MAILBOX_NOT_FOUND / MESSAGE_NOT_FOUND
- Mailbox expired or the requested resource is unavailable to this account.
- 409 · ADDRESS_CONFLICT / MAILBOX_LIMIT / IDEMPOTENCY_CONFLICT
- Address already in use, mailbox quota reached or idempotency key conflict.
- 429 · RATE_LIMITED
- Too many requests. Wait the number of seconds in Retry-After before retrying.
- 500 / 503
- The service could not complete the request. Reuse the original idempotency key when retrying a creation.