API Documentation

Automate your email workflows with simple JSON endpoints.

Open Swagger UI openapi.json

Authentication

The API supports two authentication methods:

Query Params
?address=...&secret=...
Bearer Token
Authorization: Bearer base64(address:secret)
GET

/api/new

Create new inbox

Generates a random email address and secret key. Rate limited to 100 req/hour per IP.

Parameters
domain optional
Email domain. Defaults to first available.
Response
{ "address": "vixo42@domain.com", "secret": "a1b2c3...", "expires_in": 315360000, "domains": [...] }
GET

/api/messages

🔑 Auth
List inbox messages

Returns all non-expired emails for an address. Requires authentication.

Parameters
address required
Email address
secret required
Secret key (or Bearer auth)
Response
[{ "id": "...", "from": "...", "subject": "...", "body": "...", "type": "html|text", "date": "..." }]
POST

/api/send

🔑 Auth
Send an email

Send an outbound email from your temp inbox via self-hosted SMTP (Cloudflare TCP Socket). Per-domain SMTP accounts supported. Set SMTP_HOST, SMTP_PORT, SMTP_USER, SMTP_PASS (and SMTP_USER_2/SMTP_PASS_2 for second domain) in Worker env. Rate limited to 20/hour per IP.

Parameters
address required
Sender inbox address
secret required
Secret key (or Bearer auth)
to required
Recipient email address
subject required
Email subject
text optional
Plain text body (required if no html)
html optional
HTML body (required if no text)
reply_to optional
Reply-To address
Response
{ "success": true, "message": "Email sent successfully to recipient@example.com", "from": "...", "to": "...", "subject": "...", "sent_at": "..." }
DELETE

/api/logout

🔑 Auth
Delete account

Permanently deletes the account and ALL associated emails. Irreversible.

Parameters
address required
Email address to delete
secret required
Secret key (or Bearer auth)
Response
{ "success": true, "message": "...", "deleted_at": "..." }
POST

/api/cleanup

🛡 Admin
Cleanup expired data

Removes all expired accounts, emails, and rate-limit entries. Requires X-Admin-Key header.

Parameters
X-Admin-Key required
Admin key set in Worker env as ADMIN_KEY
Response
{ "success": true, "result": { "deleted_accounts": 5, "deleted_emails": 23 }, "cleaned_at": "..." }