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

  1. In Plugins, select + and Add custom MCP server. You can also open Settings, select MCP servers, and choose Add server.
  2. 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.
  3. 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/mcp

Each 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 = 30

Claude 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 CLI
mkdir -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" --version
export 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 --json

Run 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 /mailboxes

    Create a mailbox. Pass optional name and domain fields or send {} for a random address.

  • GET /mailboxes

    List the unexpired Premium mailboxes accessible to the key.

  • GET /mailboxes/{mailboxId}/messages

    List 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/wait

    Wait 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.