Skip to main content
TempMail

API Documentation

Predictable REST endpoints with standard JSON envelopes, validation, and rate limits.

Response format

{
  "success": true,
  "message": "Request completed successfully.",
  "data": {},
  "meta": {},
  "timestamp": "ISO-8601",
  "request_id": "uuid"
}

Rate limits

  • Mailbox create: 10 requests / hour
  • Mailbox change & delete: 20 requests / hour
  • Inbox refresh: 60 requests / hour

Public endpoints

POST/api/mailbox/create

Generate a new temporary mailbox. Optional custom username and preferred domain.

{ "custom_username": "optional", "preferred_domain": "optional" }
POST/api/mailbox/change

Expire the current mailbox and create a new one.

{ "mailbox_id": "uuid" }
DELETE/api/mailbox/delete

Delete a mailbox and associated emails.

{ "mailbox_id": "uuid" }
GET/api/mailbox/status?mailbox_id=uuid

Get mailbox status, remaining lifetime, and email count.

POST/api/mailbox/refresh

Refresh inbox and check for new messages since a timestamp.

{ "mailbox_id": "uuid", "since": "optional ISO datetime" }
GET/api/inbox?mailbox_id=uuid&limit=20

List emails in a mailbox with optional pagination and filters.

GET/api/email/{id}?mailbox_id=uuid

Retrieve a single email by ID.

DELETE/api/email/{id}

Delete a single email.

{ "mailbox_id": "uuid" }
GET/api/system/status

System health check — database connectivity and metrics.