RESTful Developer API · v1

API Reference

Every endpoint below is callable directly from your browser using the Try it panel — it executes a real request against and shows the live response.

Quick Example: create inbox via curl

curl -X POST /api/v1/mailbox \
  -H "Content-Type: application/json" \
  -d '{"username":"demo","domain":"yaoi.web.id"}'

Core

· 4 endpoints

Liveness probe — no auth, no rate limit. Returns build version and timestamp.

Try it

GET /api/health

Example Response

{
  "ok": true,
  "service": "yanzxd",
  "version": "1.0.0",
  "timestamp": "2026-09-14T10:00:00.000Z",
  "commit": "110eb74"
}

List the active mail provider and every provider the build supports, with their prerequisites.

Try it

GET /api/v1/providers

Example Response

{
  "success": true,
  "data": {
    "active": { "id": "webhook", "name": "Cloudflare Email Routing / Webhook" },
    "available": [
      { "id": "webhook", "name": "Cloudflare Email Routing / Webhook", "needs": "Cloudflare Email Routing or ImprovMX/ForwardEmail" },
      { "id": "mock", "name": "KV-backed Demo", "needs": "none" }
    ],
    "customDomains": ["yaoi.web.id"]
  }
}

Public dashboard stats: active provider, domain health, config limits.

Try it

GET /api/v1/stats

Example Response

{
  "success": true,
  "data": {
    "provider": { "id": "webhook", "name": "Cloudflare Email Routing / Webhook" },
    "domains": { "total": 1, "online": 1 },
    "config": {
      "maxRequestsPerMinute": 120,
      "mailboxLifetimeMinutes": 60,
      "customDomains": ["yaoi.web.id"]
    },
    "uptime": { "timestamp": "2026-09-14T10:00:00.000Z" }
  }
}

List advertised domains the API can create mailboxes on. Cached at the edge for 5 minutes.

Try it

GET /api/v1/domains

Example Response

{
  "success": true,
  "data": {
    "domains": [
      { "domain": "yaoi.web.id", "status": "online", "availability": true, "mxStatus": "active", "lastChecked": "2026-09-14T10:00:00.000Z" }
    ],
    "count": 1
  }
}

Mailbox

· 3 endpoints

Create a new disposable mailbox. Username is optional (random if omitted). Domain is optional (first available if omitted). lifetimeMinutes (1-1440) overrides the default 60-minute expiry.

Parameters

Name	In	Type	Description
username	body	string	Optional. 2-30 chars; alphanumeric, dots, hyphens, underscores only.
domain	body	string	Optional. Must match one of the advertised domains.
lifetimeMinutes	body	number	Optional. 1-1440. Default: 60.

Try it

Request Body (JSON)

POST /api/v1/mailbox

Example Response

{
  "success": true,
  "data": {
    "id": "mb_hook_abc1234",
    "address": "demo@yaoi.web.id",
    "domain": "yaoi.web.id",
    "createdAt": "2026-09-14T10:00:00.000Z",
    "expiresAt": "2026-09-14T11:00:00.000Z",
    "messageCount": 0
  }
}

Fetch mailbox metadata (id, expiry, messageCount). Returns 404 once expired.

Parameters

Name	In	Type	Description
address*	path	string	Full email address.

Try it

address (path, required)

GET /api/v1/mailbox/{address}

Example Response

{
  "success": true,
  "data": {
    "id": "mb_hook_abc1234",
    "address": "demo@yaoi.web.id",
    "domain": "yaoi.web.id",
    "createdAt": "2026-09-14T10:00:00.000Z",
    "expiresAt": "2026-09-14T11:00:00.000Z",
    "messageCount": 2
  }
}

Permanently delete a mailbox and all its stored messages.

Parameters

Name	In	Type	Description
address*	path	string	Full email address.

Try it

address (path, required)

DELETE /api/v1/mailbox/{address}

Example Response

{ "success": true, "data": { "deleted": true, "address": "demo@yaoi.web.id" } }

Messages

· 5 endpoints

List messages for a mailbox. Supports pagination and unread filter.

Parameters

Name	In	Type	Description
address*	path	string	Full email address.
unread	query	boolean	Only return unread messages.
limit	query	number	Cap to N messages. Max 200.(default: `200`)
offset	query	number	Skip first N messages.(default: `0`)

Try it

address (path, required) unread (query) limit (query) offset (query)

GET /api/v1/mailbox/{address}/messages

Example Response

{
  "success": true,
  "data": {
    "address": "demo@yaoi.web.id",
    "total": 2,
    "count": 2,
    "offset": 0,
    "limit": 200,
    "hasMore": false,
    "messages": [
      {
        "id": "msg_inbound_xyz",
        "mailboxId": "mb_hook_abc1234",
        "mailboxAddress": "demo@yaoi.web.id",
        "from": { "name": "GitHub Security", "address": "noreply@github.com" },
        "to": [{ "address": "demo@yaoi.web.id" }],
        "subject": "Your verification code",
        "preview": "Please use the following verification code...",
        "receivedAt": "2026-09-14T10:01:00.000Z",
        "isRead": false,
        "hasAttachments": false
      }
    ]
  }
}

Fetch full message detail including sanitized HTML body and attachment list.

Parameters

Name	In	Type	Description
address*	path	string	Full email address.
id*	path	string	Message ID.

Try it

address (path, required) id (path, required)

GET /api/v1/mailbox/{address}/messages/{id}

Example Response

{
  "success": true,
  "data": {
    "id": "msg_inbound_xyz",
    "from": { "name": "GitHub Security", "address": "noreply@github.com" },
    "subject": "Your verification code",
    "textBody": "Your code is 123456",
    "htmlBody": "<div>Your code is <b>123456</b></div>",
    "sanitizedHtml": "<div>Your code is <b>123456</b></div>",
    "receivedAt": "2026-09-14T10:01:00.000Z",
    "isRead": true,
    "hasAttachments": false,
    "attachments": []
  }
}

Delete one message. Mailbox stays alive.

Parameters

Name	In	Type	Description
address*	path	string	Full email address.
id*	path	string	Message ID.

Try it

address (path, required) id (path, required)

DELETE /api/v1/mailbox/{address}/messages/{id}

Example Response

{ "success": true, "data": { "deleted": true, "id": "msg_inbound_xyz" } }

Delete every message in a mailbox. Mailbox stays alive.

Parameters

Name	In	Type	Description
address*	path	string	Full email address.

Try it

address (path, required)

DELETE /api/v1/mailbox/{address}/messages

Example Response

{ "success": true, "data": { "address": "demo@yaoi.web.id", "deleted": true, "count": 0 } }

Mark every unread message in the mailbox as read. Returns the number of messages updated.

Parameters

Name	In	Type	Description
address*	path	string	Full email address.

Try it

address (path, required)

POST /api/v1/mailbox/{address}/mark-all-read

Example Response

{ "success": true, "data": { "address": "demo@yaoi.web.id", "updated": 3 } }

Search

· 3 endpoints

Substring search across subject, from-address, from-name, and preview. Case-insensitive.

Parameters

Name	In	Type	Description
address*	path	string	Full email address.
q*	query	string	Search keyword.

Try it

address (path, required) q (query, required)

GET /api/v1/mailbox/{address}/search

Example Response

{
  "success": true,
  "data": {
    "address": "demo@yaoi.web.id",
    "query": "github",
    "count": 1,
    "messages": []
  }
}

Download all messages. format=jsonl (default) returns one JSON object per line. format=json returns pretty-printed array.

Parameters

Name	In	Type	Description
address*	path	string	Full email address.
format	query	string	`jsonl` (default) or `json`.(default: `jsonl`)

Try it

address (path, required) format (query)

GET /api/v1/mailbox/{address}/export

Example Response

// Content-Type: application/x-ndjson or application/json
// Content-Disposition: attachment; filename="demo_at_yaoi.web.id-2026-09-14.jsonl"

Server-Sent Events stream. Polls KV every 3s and emits `messages` when new mail arrives. Also emits `ping` heartbeats and `mailbox_status` lifecycle events.

Parameters

Name	In	Type	Description
address*	path	string	Full email address.

Try it

address (path, required)

GET /api/v1/mailbox/{address}/events

Example Response

event: connected
data: {"address":"demo@yaoi.web.id","timestamp":"2026-09-14T10:00:00.000Z"}

event: mailbox_status
data: {"mailbox":{"id":"...","address":"demo@yaoi.web.id",...}}

event: messages
data: {"messages":[]}

event: ping
data: {"time":1737000000000}

Webhook

· 1 endpoint

Inbound email webhook receiver. Authenticates via WEBHOOK_SECRET env (sent as `Authorization: Bearer <secret>` or `x-webhook-secret: <secret>`). Auto-creates the mailbox on first delivery.

Parameters

Name	In	Type	Description
to*	body	string	Recipient address.
from*	body	string	Sender address.
fromName	body	string	Optional display name.
subject	body	string	Email subject.
text	body	string	Plain-text body.
html	body	string	HTML body (will be sanitized on render).

Try it

Request Body (JSON)

POST /api/v1/webhook/inbound

Example Response

{
  "success": true,
  "data": {
    "id": "msg_inbound_xyz",
    "to": "demo@yaoi.web.id",
    "subject": "Your verification code",
    "receivedAt": "2026-09-14T10:01:00.000Z"
  }
}

Rate limits

• Read endpoints — 240 req/min/IP
• Mailbox creation — 30 req/min/IP
• Delete operations — 60 req/min/IP
• Inbound webhook — 120 req/min/IP
• Over-quota returns 429 with Retry-After

Response shape

// success
{ "success": true, "data": { ... } }

// error
{
  "success": false,
  "error": {
    "code": "INVALID_ADDRESS",
    "message": "Invalid email address",
    "details": null
  }
}