Temporary email API

Create a disposable inbox and read incoming messages from a script or test server. This is the same hosted API used by our temporary email tool. It is free to use, with no signup, credit card, or developer API key.

Base URL: https://plainlykit.com/tools/temporary-email/api. Use HTTPS server-to-server requests. Cross-origin browser requests are not supported; do not expose inbox tokens in public frontend code.

1. Create an inbox

curl -X POST 'https://plainlykit.com/tools/temporary-email/api/mailboxes' \
  -H 'Content-Type: application/json' \
  -d '{}'

The 201 JSON response contains id, address, token, createdAt, and expiresAt. Timestamps are Unix milliseconds. Send your test email to address, and keep the returned ID and token private. The token is shown only when the inbox is created and cannot be recovered.

An empty object selects a random available domain. To choose one, first request GET /config, then send {"domain":"one-of-the-returned-domains"} instead.

2. Check incoming messages

Replace INBOX_ID and INBOX_TOKEN below with the values returned at creation.

curl 'https://plainlykit.com/tools/temporary-email/api/mailboxes/INBOX_ID/messages' \
  -H 'Authorization: Bearer INBOX_TOKEN'

The response contains mailbox metadata and a messages array, newest first. Each message includes id, sender, subject, preview, receivedAt, size, and attachmentCount. An empty inbox returns an empty array. Poll at most once every five seconds, stop when your message arrives, and back off on errors.

3. Read a message

curl 'https://plainlykit.com/tools/temporary-email/api/mailboxes/INBOX_ID/messages/MESSAGE_ID' \
  -H 'Authorization: Bearer INBOX_TOKEN'

This returns the message ID, sender, subject, received timestamp, plain text, and attachment filenames and MIME types. Append /raw to download the original .eml file with its attachments. Treat all email content and attachments as untrusted.

4. Delete the inbox

curl -X DELETE 'https://plainlykit.com/tools/temporary-email/api/mailboxes/INBOX_ID' \
  -H 'Authorization: Bearer INBOX_TOKEN'

A successful deletion returns {"deleted":true}. Access is revoked immediately. You can also delete a single message with DELETE /mailboxes/INBOX_ID/messages/MESSAGE_ID and the same authorization header.

Free limits and privacy

Inboxes expire 24 hours after creation. The API token works until expiry or deletion; it is independent of the browser tool’s reload behavior.
Up to 100 accepted messages per inbox lifetime, each at most 2 MiB. Deleting messages does not reset this delivery allowance.
Creation is limited to 10 inboxes per IP per minute at each Cloudflare location. Limits are shared with the web tool.
Receive only: there is no sending, replying, forwarding, or webhook endpoint.
No uptime guarantee. Use for non-sensitive testing, not lasting accounts, purchases, or password recovery. Some senders block disposable addresses.

Expired inboxes are regularly removed from active storage. Deleted message metadata may remain in provider recovery history for up to seven days. See our privacy policy. Keep tokens out of URLs, logs, and source control: anyone holding a token and its inbox ID can read and delete that inbox.

Errors

Errors return JSON with an error string: 400 for invalid creation requests, 401 for missing or incorrect inbox credentials, 403 for cross-origin inbox creation, 404 for missing messages or routes, 405 for unsupported inbox methods, 410 for expired inboxes, 429 for the creation limit, and 503 when the service is temporarily unavailable. Do not retry authorization errors; create a new inbox if access has expired.

Questions? Contact sofia@plainlykit.com. For date calculations, see our free date API.