TempMail Public API

A free REST API to generate disposable email addresses and receive messages — no signup, no API key required.

Free & No Auth REST / JSON 1h TTL Rate Limited

Base URL

https://mail.ddd.io.vn/api/v1 All responses are JSON

All API endpoints are prefixed with /api/v1. Requests and responses use JSON. No authentication is required.

Rate Limits

Rate limits are per IP address, reset every 60 seconds. Exceeded requests return HTTP 429.

Endpoint groupLimit / minute
GET endpoints (read)60 req/min
POST /mailbox (create)30 req/min
DELETE /mailbox (delete all)20 req/min
DELETE /messages/:id30 req/min

Error Format

All errors return a JSON body with an error field and the appropriate HTTP status code.

JSON { "error": "Message not found" }
CodeMeaning
200OK
201Created
400Bad Request — invalid parameter
404Not Found
429Too Many Requests — rate limit hit

Health Check

GET /api/v1/health Service status

Returns current service status and available domains.

Response 200
JSON { "status": "ok", "version": "1.0.0", "service": "TempMail API", "timestamp": "2025-01-01T00:00:00.000Z", "domains": ["mail.ddd.io.vn", "c3nbkhiem.org"] }
Try it

List Domains

GET /api/v1/domains Available mail domains

Returns the list of supported mail domains you can use when creating a mailbox.

Response 200
JSON { "domains": ["mail.ddd.io.vn", "c3nbkhiem.org"], "count": 2, "primary": "mail.ddd.io.vn" }
Try it

Create Mailbox

POST /api/v1/mailbox Generate a new temp email

Creates a new temporary mailbox. Emails expire after 1 hour. You can optionally supply a custom name and choose a domain.

Request Body (optional, JSON)
FieldTypeDescription
name optional string Custom inbox name. Only a–z, 0–9, dot, dash, underscore. If omitted, a random name is generated.
domain optional string Mail domain: mail.ddd.io.vn or c3nbkhiem.org. Defaults to mail.ddd.io.vn.
Example request
cURL curl -X POST https://mail.ddd.io.vn/api/v1/mailbox \ -H "Content-Type: application/json" \ -d '{"name": "hello", "domain": "c3nbkhiem.org"}'
Response 201
JSON { "email": "hello@c3nbkhiem.org", "name": "hello", "domain": "c3nbkhiem.org", "expires_at": "2025-01-01T01:00:00.000Z", "inbox_url": "/api/v1/mailbox/hello%40c3nbkhiem.org/messages" }

Get Messages

GET /api/v1/mailbox/:email/messages List inbox messages

Returns all messages for a given email address. The :email must be URL-encoded.

Path parameter
ParamTypeDescription
:email requiredstringURL-encoded email address, e.g. hello%40mail.ddd.io.vn
Query parameters
ParamDefaultDescription
page optional1Page number (1-based)
limit optional20Items per page, max 50
Example request
cURL curl https://mail.ddd.io.vn/api/v1/mailbox/hello%40mail.ddd.io.vn/messages
Response 200
JSON { "email": "hello@mail.ddd.io.vn", "messages": [ { "id": "abc123", "from_name": "GitHub", "from_email": "noreply@github.com", "subject": "Verify your email", "received_at": 1735689600000, "is_read": 0 } ], "pagination": { "page": 1, "limit": 20, "total": 1, "pages": 1 } }

Read Message

GET /api/v1/messages/:id Get full message content

Fetches the full content of a message including HTML and plain text body. Also marks the message as read.

ParamTypeDescription
:id requiredstringMessage ID from the inbox list
Example request
cURL curl https://mail.ddd.io.vn/api/v1/messages/abc123
Response 200
JSON { "id": "abc123", "to_email": "hello@mail.ddd.io.vn", "from_name": "GitHub", "from_email": "noreply@github.com", "subject": "Verify your email", "body_text": "Click here to verify...", "body_html": "<p>Click here to verify...</p>", "received_at": 1735689600000, "is_read": 1 }

Delete Message

DELETE /api/v1/messages/:id Delete a single message

Permanently deletes a single message by ID.

Example request
cURL curl -X DELETE https://mail.ddd.io.vn/api/v1/messages/abc123
Response 200
JSON { "success": true }

Delete Mailbox

DELETE /api/v1/mailbox/:email Delete all messages in inbox

Permanently deletes all messages for the given email address. The :email must be URL-encoded.

Example request
cURL curl -X DELETE https://mail.ddd.io.vn/api/v1/mailbox/hello%40mail.ddd.io.vn
Response 200
JSON { "success": true, "deleted": 3 }

Quick Example

Full workflow — generate an address, wait for email, read it:

JavaScript // 1. Create a mailbox const res = await fetch('https://mail.ddd.io.vn/api/v1/mailbox', { method: 'POST', headers: { 'Content-Type': 'application/json' } }); const { email, inbox_url } = await res.json(); console.log('Your temp email:', email); // 2. Poll for messages const poll = setInterval(async () => { const r = await fetch(`https://mail.ddd.io.vn${inbox_url}`); const { messages } = await r.json(); if (messages.length > 0) { clearInterval(poll); // 3. Read first message const msg = await ( await fetch(`https://mail.ddd.io.vn/api/v1/messages/${messages[0].id}`) ).json(); console.log('Subject:', msg.subject); console.log('Body:', msg.body_text); } }, 3000);