API Documentation

Authentication

All API requests require an API key passed in the Authorization header:

Authorization: Bearer YOUR_API_KEY

Get your API key from the Developer Dashboard.

Rate Limits

Default rate limit: 1000 requests per 60 seconds

When rate limit is exceeded, you'll receive a 429 Too Many Requests response with a Retry-After header.

Base URL

https://api.tempmail.dfulabs.com

Endpoints

Get Available Domains

GET /api/domains

Response: 200 OK
[
  "appsclash.cfd",
  "bulbexposures.shop"
]

List Your Inboxes

Returns only inboxes owned by your API key.

GET /api/inboxes?limit=50&offset=0

Response: 200 OK
{
  "inboxes": [
    {
      "id": "uuid",
      "address": "test@appsclash.cfd",
      "is_public": false,
      "created_at": 1234567890
    }
  ],
  "limit": 50,
  "offset": 0
}

Create Inbox

Note: Inboxes created via API are always private and linked to your account.

POST /api/inbox
Content-Type: application/json

{
  "name": "myinbox",
  "domain": "appsclash.cfd"
}

Response: 201 Created
{
  "id": "uuid",
  "address": "myinbox@appsclash.cfd",
  "is_public": false
}

List Emails

Access emails from your private inboxes or public inboxes.

GET /api/inbox/:id/emails

Response: 200 OK
[
  {
    "id": "uuid",
    "sender": "sender@example.com",
    "subject": "Test Email",
    "body_text": "Plain text content",
    "body_html": "<p>HTML content</p>",
    "created_at": 1234567890
  }
]

Error: 403 Forbidden (if not owner and inbox is private)
{
  "error": "Access denied"
}

Delete Inbox

Only the inbox owner can delete it.

DELETE /api/inbox/:id

Response: 200 OK
{
  "ok": true
}

Error: 403 Forbidden (if not owner)
{
  "error": "Only inbox owner can delete"
}

Inbox Privacy

• Private Inbox: Only you (the owner) can read emails. Created via API.
• Public Inbox: Anyone can read emails if they know the inbox ID. Created via web interface.

Error Responses

• 401 Unauthorized - Invalid or missing API key
• 403 Forbidden - Access denied (not owner or private inbox)
• 429 Too Many Requests - Rate limit exceeded
• 400 Bad Request - Invalid request parameters
• 404 Not Found - Resource not found
• 409 Conflict - Address already taken
• 500 Internal Server Error - Domain validation failed

Example Usage

Create a private inbox

curl -X POST https://api.tempmail.dfulabs.com/api/inbox \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "test",
    "domain": "appsclash.cfd"
  }'

List your inboxes

curl https://api.tempmail.dfulabs.com/api/inboxes \
  -H "Authorization: Bearer YOUR_API_KEY"

Get emails from inbox

curl https://api.tempmail.dfulabs.com/api/inbox/YOUR_INBOX_ID/emails \
  -H "Authorization: Bearer YOUR_API_KEY"

Delete inbox

curl -X DELETE https://api.tempmail.dfulabs.com/api/inbox/YOUR_INBOX_ID \
  -H "Authorization: Bearer YOUR_API_KEY"