Conventions

• Base URL: https://api.mailcycle.email
• JSON in, JSON out. Send Content-Type: application/json on every request with a body.
• Identifiers are prefixed and opaque: acct_ accounts, ibx_ email addresses, msg_ messages, wkr_ devices, grp_ device groups, key_ API keys, whk_ webhooks, whd_ webhook deliveries, evt_ events, tkt_ support requests, tkm_ their messages, pay_ payments and act_ activity entries. API key tokens start with mak_, session tokens with mst_ and device credentials with wkt_.
• Client-chosen ids. Records that carry sealed data bound to their id (addresses, messages, devices, device groups, API keys, webhooks, support requests) take an id you generate, so the seal can exist before the record. The server checks the shape and uniqueness.
• Timestamps are ISO 8601 in UTC.
• Money is integer minor units: 9900 is $99.00.
• Pagination. GET /workers, GET /inboxes/:id/messages and GET /webhook-endpoints/:id/deliveries take ?limit= (default 50, at most 200) and ?cursor= from the previous response’s nextCursor. GET /activity works the same way with a default of 20. GET /workers and GET /inboxes/:id/messages also return a total. GET /workers/messages pages back with ?before= from olderCursor instead. Treat cursors as opaque. A null cursor means the end.
• Ownership. A record you do not own answers 404, the same as one that does not exist.
• Health and status. GET /health answers { "service": "mailcycle", "ok": true, "version": "…" }. GET /status answers ok, maintenance (mode, message, startedAt) and features, which feature switches are on. Neither needs a token. During maintenance, requests return 503 maintenance, or writes only return 503 read_only, with a Retry-After header.
• HTTPS only. A plain HTTP request is refused with 403 https_required, not redirected.