API Documentation

Base URL

All API endpoints are relative to the base URL. For the public service, the base URL is https://api.m2u.io.

GET /v1/domains

Returns the list of available email domains. No authentication required.

• Response: { domains: string[] }
• Example: GET /v1/domains → { "domains": ["cpu.edu.kg", "do4.tech", ...] }

POST /v1/mailboxes/auto

Creates a random temporary mailbox automatically. No authentication required. Rate limited.

• Request body (optional): { token?: string } — pass an existing token to reuse a mailbox
• Response: { mailbox: { token, view_token, local_part, domain, expires_at } }
• Rate limit: 5 per minute, 20 per day per IP

POST /v1/mailboxes/custom

Creates a custom mailbox with your chosen prefix and domain. Requires Turnstile verification.

• Request body: { localPart: string, domain: string, turnstileToken: string }
• Response: { mailbox: { token, view_token, local_part, domain, expires_at } }
• Errors: address_taken, invalid_domain, turnstile_failed, daily_limit_exceeded

GET /v1/mailboxes/:token/messages?view=VIEW_TOKEN

Lists all messages in a mailbox. Requires both the mailbox token and the view_token for security.

• Response: { messages: [{ id, from_addr, subject, received_at }] }
• Messages are sorted by received_at descending, limit 50

GET /v1/mailboxes/:token/messages/:id?view=VIEW_TOKEN

Retrieves the full content of a single email, including the HTML body and plain text.

• Response: { message: { id, from_addr, subject, text_body, html_body, received_at } }

GET /v1/mailboxes/:token/stream?view=VIEW_TOKEN

Server-Sent Events (SSE) endpoint for real-time email notifications. Connect to receive instant updates when new mail arrives.

• Event: connected — sent on successful connection
• Event: mail — sent when a new email is received, includes { id, from, subject, receivedAt }
• Keep-alive pings are sent every 20 seconds

Data Retention

Mailboxes are active for 7 days. Emails are automatically deleted after 24 hours. All data is permanently removed after expiration.

Rate Limiting

API endpoints are rate-limited per IP address. If you exceed the limit, you will receive an error response with { error: "rate_limited" }.

• Auto mailbox creation: 5/min, 20/day
• Custom mailbox creation: 5/min, 3/day
• Message reading: 100/min