Build With The TempMail API.

Getting Started

Step 1: Request An API Key From The Website Administrator. The Administrator Configures It On The Server.

Step 2: Choose An Enabled Domain Using The Domains Endpoint.

Step 3: Create A Mailbox And Store Its Access Token Securely.

Step 4: Read The Inbox And Open Individual Messages Using Both Credentials.

Use Your Own Website Domain As The Base URL, For Example https://your-site.example. HTTPS Is Required For Production.

Authentication

Every Public API Request Requires An API Key In The Authorization Header.

Authorization: Bearer YOUR_API_KEY

Reading Messages Also Requires The Mailbox Token Returned During Mailbox Creation.

x-mailbox-token: YOUR_MAILBOX_TOKEN

Never Put API Keys Or Mailbox Tokens In Public Frontend Code, URLs, Logs, Or Shared Screenshots.

1. List Available Domains

Get The Enabled Domains That Can Receive Mail.

curl -H "Authorization: Bearer YOUR_API_KEY" \
  https://your-site.example/api/v1/domains

Example Response:

{ "domains": ["example.com"] }

2. Create A Mailbox

Provide A Username (3–32 Characters), An Enabled Domain, And An Optional Password (8–128 Characters When Set).

curl -X POST https://your-site.example/api/v1/mailboxes \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"username":"example","domain":"example.com","password":""}'

Example Response (HTTP 201):

{
  "email": "[email protected]",
  "token": "YOUR_MAILBOX_TOKEN"
}

The Token Is A Secret. Store It On Your Server. An Existing Mailbox Returns HTTP 409.

3. Read Inbox

URL-Encode The Email Address In The Path. The Response Contains Message Summaries And A Pagination Token.

curl -H "Authorization: Bearer YOUR_API_KEY" \
  -H "x-mailbox-token: YOUR_MAILBOX_TOKEN" \
  "https://your-site.example/api/v1/mailboxes/example%40example.com/messages"

Example Response:

{
  "messages": [
    {"id":"MESSAGE_ID","from":"[email protected]","subject":"Verification","date":"...","snippet":"..."}
  ],
  "nextPageToken": null
}

To Read Older Messages, Send The Returned Token As The pageToken Query Parameter. Continue Until nextPageToken Is null.

GET /api/v1/mailboxes/example%40example.com/messages?pageToken=NEXT_PAGE_TOKEN

4. Read Message Details

Use The Message ID From The Inbox Response. The Server Verifies That The Message Belongs To The Requested Mailbox.

curl -H "Authorization: Bearer YOUR_API_KEY" \
  -H "x-mailbox-token: YOUR_MAILBOX_TOKEN" \
  "https://your-site.example/api/v1/mailboxes/example%40example.com/messages/MESSAGE_ID"

Response Fields Include id, from, to, subject, date, html, text, And hasHtml.

Errors And Rate Limits

HTTP 400: Invalid Input Or Pagination Token. HTTP 401: Missing Or Invalid API Key. HTTP 403: Invalid Mailbox Token. HTTP 404: Message Not Found. HTTP 409: Mailbox Already Exists. HTTP 429: Too Many Requests. HTTP 502: Gmail Service Error.

Public API Access Is Limited To 30 Requests Per Minute Per IP, In Addition To The General API Limit. Mailbox Creation Has An Additional Limit Of 5 Requests Per Minute.

Wait And Retry After HTTP 429. Avoid Polling Too Frequently. Gmail Access Requires Valid OAuth Configuration On The Server.

Security And Troubleshooting

Keep Your API Key And Mailbox Token Server-Side. Use HTTPS, Validate User Input, And Avoid Exposing Message Contents To Other Users.

If The Inbox Is Empty, Check That Your Domain Has Working MX Or Forwarding, That Gmail OAuth Is Connected, And That The Message Was Delivered To The Requested Address.

If You Receive HTTP 403, Confirm The Mailbox Token Matches The Email Address. For HTTP 401, Confirm Your Bearer API Key.

API Keys Are Configured Through PUBLIC_API_KEYS On The Server. Do Not Publish The Value.