The same API the console runs on.

What is built

What the API offers today, and what is planned.

Authentication

All requests are made over HTTPS to https://api.mailcycle.email and carry a bearer token. There are two kinds of identity.

• Operator sessions represent your account. They can manage devices, email addresses and billing, and read any mail on the account. You obtain one by running the recovery-phrase handshake: POST /accounts/challenge for a nonce, then POST /accounts/verify with a proof computed from the challenge.
• Worker credentials represent one device. They are minted during pairing, scoped to that device, and can read only its own mail. They are never issued by hand.

curl https://api.mailcycle.email/workers \
  -H "Authorization: Bearer $MAILCYCLE_TOKEN"

Conventions

• JSON in, JSON out. Content-Type: application/json on every request with a body.
• Identifiers are prefixed and opaque: wkr_ devices, ibx_ email addresses, msg_ messages, acct_ accounts.
• Timestamps are ISO 8601 in UTC.
• Monetary amounts are integer minor units: 9900 is $99.00.
• GET /workers and GET /inboxes/:id/messages are cursor paginated. Pass ?limit= (default 50, at most 200) and ?cursor= from the previous response's nextCursor; a null nextCursor means the end.

Endpoints

Pairing flow

Pairing follows the OAuth device flow: a device with no keyboard and no account is claimed by an authenticated one.

Worker                          Backend                       Operator
  │                                │                              │
  ├─ POST /workers/pairing-session ►                              │
  │                                ├─ mint token + 8-digit code   │
  │◄─ { token, code } ─────────────┤   no timer; single use       │
  │                                │                              │
  ├─ render QR(token) + code       │                              │
  ├─ GET …/pairing-session/:token ─►                              │
  │◄─ state: waiting ──────────────┤                              │
  │                                │◄─ POST /workers/pair/lookup ─┤
  │◄─ state: operator_detected ────┤                              │
  │                                │◄─ POST /workers/pair ────────┤
  │                                ├─ consume session (once)      │
  │                                ├─ create Worker + credential  │
  │◄─ awaiting_inbox + credential ─┤   (credential sent once)     │
  │                                │◄─ POST /workers/:id/inboxes ─┤
  │                                │◄─ POST /workers/:id/keys ────┤
  │◄─ state: inbox_assigned ───────┤                              │
  └─ open mail interface           │                              │

A session moves through four states: waiting, operator_detected, awaiting_inbox and inbox_assigned. A device that gives up can cancel its session with DELETE /workers/pairing-session/:token.

The guarantees the flow depends on:

• Pairing tokens are cryptographically random and server-generated.
• The 8-digit code is a lookup key onto the token, not the secret itself.
• Sessions do not expire on a timer, so a device can wait as long as it needs to. Each is consumable exactly once, and an unclaimed session can be cancelled. Sessions nobody claims are removed after 14 days.
• Claiming requires a valid Operator bearer token. On Free, claiming a second device returns worker_limit_reached.
• The device credential is minted only after the Operator confirms, is scoped to that one device, and is independently revocable.
• Code lookups are limited per account and per IP: after ten failed lookups in five minutes, further lookups return 429.

Events

Your code cannot receive events yet: there is no socket to subscribe to and no webhook to register. The names below are the events Mailcycle's own apps already pass between screens, and the contract for the public stream.

Each frame is { "type": …, "payload": … }. Payloads carry ids, never content: to show a message, fetch it by id and decrypt it in your client.

{
  "type": "message.received",
  "payload": {
    "messageId": "msg_91be",
    "inboxId": "ibx_4c7a"
  }
}

Webhook signing and delivery guarantees will be documented here when webhooks ship.

Errors

Errors carry an HTTP status and a stable machine-readable code alongside a human message. Match on code, never on the message text.

{
  "code": "downgrade_blocked",
  "message": "You have 340 email addresses, which is more than Operator allows. Delete 90 first."
}

Rate limits

Requests are limited per account and per IP in two layers: short-term limits at Cloudflare's edge, and hourly and 30-day quotas behind them. A limited request returns 429 with a Retry-After header in seconds. The edge limits absorb floods and are not published as fixed numbers.

The quota you are most likely to meet is your plan's message allowance, from 3,000 a month on Free to 20,000,000 on Fleet (see pricing). Sending and reading mail back have hourly limits, and pairing-code lookups are limited most tightly.

If you are planning a bulk import or a migration that may hit these limits, tell us first.

Roadmap

What we are building next, in the order we expect to ship it. Nothing here is available today.

• API keys. Long-lived, scoped and individually revocable, issued from the console, so automation does not need a recovery phrase.
• Webhooks. Signed deliveries for inbound mail and device lifecycle events, with retries and a delivery log.
• Event stream. The socket described above, open to customer code.
• SDKs. Thin typed clients over the REST surface, including client-side decryption, which the API cannot do.
• A Developer section in the console. Keys, usage, event logs and developer settings in one place.

There are no dates. When something on this list ships it is announced in the changelog and the badge above it changes.