REST API documentation

GET/api/email/{domain}/{user}/

Get a paginated list of a user's emails. List responses contain metadata only (no body / html_body).

Parameter	Location	Description
domain	path	Email domain, e.g. example.com
user	path	Username, e.g. testuser
page	query, optional	Page number (default 1)
limit	query, optional	Items per page (default 20, maximum 100)

curl -X GET "https://BASE_URL/api/email/example.com/testuser/?page=1&limit=20"

{
  "emails": [
    {
      "id": 123,
      "subject": "Welcome",
      "sender": "[email protected]",
      "date": "2026-09-30T10:30:00.000Z",
      "has_attachments": false,
      "size": 1234
    }
  ],
  "total": 5,
  "page": 1,
  "limit": 20,
  "has_more": false
}

GET/api/email/{domain}/{user}/{email_id}

Get the full details of an email.

curl -X GET "https://BASE_URL/api/email/example.com/testuser/123"

DELETE/api/email/{domain}/{user}/{email_id}

Delete a specific email.

curl -X DELETE "https://BASE_URL/api/email/example.com/testuser/123"

{ "status": "deleted" }

POST/api/add-domain/{domain}

Add a new domain or update an existing domain's online status. The domain must have an MX record pointing to the system's hostname to be accepted (status added, is_online: true).

curl -X POST "https://BASE_URL/api/add-domain/newdomain.com"

// Successfully added
{ "status": "added", "domain": "newdomain.com", "is_online": true }

// Existing domain: update its status
{ "status": "updated", "domain": "newdomain.com", "is_online": false }

GET/api/all-domains/ & /api/random-domains/

All online domains (private, token required):

curl -X GET "https://BASE_URL/api/all-domains/" \
  -H "X-Domain-Token: YOUR_TOKEN"

Random online domains (public):

curl -X GET "https://BASE_URL/api/random-domains/?limit=10"

{ "domains": ["domain1.com", "domain2.com"], "total": 2 }

GET/api/check-mx/{domain}

Check whether a domain has a valid MX record pointing to the system.

curl -X GET "https://BASE_URL/api/check-mx/example.com"

{ "result": "online" }   // or "offline"

Error handling

Code	Meaning
200	Success
400	Invalid request (e.g. malformed domain/email)
401	Missing or invalid token for a private endpoint
404	Email not found
429	Rate limit exceeded

{ "detail": "Domain not found" }

Important notes

• Email addresses must use the format [email protected]
• Only domains with valid MX records have "online" status
• Emails and inactive domains are automatically deleted after 3 days
• The service only receives email — sending and SMTP relay are not supported
• The API applies per-IP rate limits
• The 3-day retention period applies to the live service; backups may retain copies longer. Permanent deletion from all copies is not guaranteed at that time.
• Custom-domain inboxes remain public and may be blocked by third-party services. Acceptance and delivery are not guaranteed.