API Documentation

Disposable email API that runs on Cloudflare Worker, D1, R2, Queues, and Email Routing.

View Endpoints Custom Domain Setup

Quick Start

Create or open a mailbox

Use any active disposable domain configured in your Worker.

Send email to that address

Messages are ingested by Cloudflare Email Routing and parsed asynchronously.

Fetch messages via API

Use the same `/api/v1` contract the frontend already consumes.

curl "https://app.pickymail.me/api/v1/mailbox?address=test@pickymail.me"

Base URL

https://app.pickymail.me

Storage

Metadata: Cloudflare D1

Body and files: Cloudflare R2

API Endpoints

All endpoints return JSON responses except attachment downloads.

POST /api/v1/mailboxes

Create Mailbox

Create or refresh a mailbox in D1 before the frontend activates it.

Request Body

{
  "localPart": "test",
  "domain": "pickymail.me"
}

Response

{
  "mailbox": {
    "id": "mbx_xxx",
    "address": "test@pickymail.me",
    "domain": "pickymail.me",
    "expiresAt": "2026-04-22T10:00:00.000Z"
  }
}

POST /api/v1/mailboxes/open

Open Existing Mailbox

Open by address. If it does not exist yet and the domain is active, the backend lazily creates it.

Request Body

{
  "address": "test@pickymail.me"
}

GET /api/v1/mailbox

List Mailbox Messages

Retrieve message metadata for a mailbox. This is the same endpoint the frontend polls every few seconds.

cURL Example

curl "https://app.pickymail.me/api/v1/mailbox?address=test@pickymail.me"

Response

{
  "messages": [
    {
      "id": "msg_xxx",
      "from": "sender@example.com",
      "subject": "Welcome!",
      "date": "2026-04-21T12:00:00.000Z",
      "size": 1234,
      "otp": "123456"
    }
  ]
}

GET /api/v1/message/{id}

Get Message Details

Fetch rendered message content, recipients, and attachment metadata.

cURL Example

curl "https://app.pickymail.me/api/v1/message/msg_xxx?mailbox=test@pickymail.me"

DELETE /api/v1/message/{id}

Delete Message

Soft-delete the message immediately and hand file cleanup to the delete queue.

cURL Example

curl -X DELETE "https://app.pickymail.me/api/v1/message/msg_xxx?mailbox=test@pickymail.me"

GET /api/v1/attachment/{id}

Download Attachment

Streams the R2 object for an attachment after mailbox ownership is verified.

Custom Domain Setup

Point your domain to Cloudflare Email Routing so inbound messages reach the Worker.

DNS Configuration

1. Add MX Record

Type	MX
Host	@
Value	route.mx.cloudflare.net
Priority	10
TTL	3600

2. Enable Email Routing: Create a catch-all route that sends inbound messages to the Worker `email()` handler.

3. Activate the domain: Add the domain to D1 or `BUILTIN_DOMAINS` so the API accepts it.