HTTP API

The API the control panel is built on. Everything under /api, JSON in and JSON out.

There is no separate API-key mechanism: the panel API authenticates with the same session cookie a browser gets. If you are automating against it, sign in and keep the cookie.

Authentication#

curl -c jar -X POST https://mail.example.com/api/auth/login \
  -H 'content-type: application/json' \
  -d '{"email":"you@example.com","password":"..."}'

curl -b jar https://mail.example.com/api/auth/me

The session is a corsair_session cookie, HttpOnly, SameSite=Lax, valid for 14 days.

Sessions are rows, not just signed tokens. The signature alone is not enough — a revoked session stops working immediately, which a stateless token cannot do.

Errors#

One shape, everywhere:

{
  "statusCode": 404,
  "name": "not_found",
  "message": "Domain not found."
}

name is the machine-readable slug to switch on. It stays stable even when the message is reworded, so never match on message.

402 rather than 403 for plan gating, so a client can render an upgrade prompt rather than an error.

404 rather than 403 for a resource belonging to another account. The distinction would leak existence.

Postgres constraint violations are translated rather than surfaced as 500s — a unique violation is a 409.

Rate limits#

Ten requests per second per principal by default (RATE_LIMIT_PER_SECOND); unauthenticated requests are limited per IP. Sign-in and sign-up have their own limit of five per second per IP.

A 429 carries:

retry-after: 1
ratelimit-limit: 10
ratelimit-remaining: 0
ratelimit-reset: 1

Pagination#

List endpoints take page, per_page, search, sort, and direction.

per_page must be one of 10, 25, 50, 100; anything else falls back to 10. direction is asc or desc. Sort columns are chosen from a per-endpoint whitelist, so an unrecognised sort is ignored rather than erroring.

{
  "object": "list",
  "data": [ ... ],
  "page": 1,
  "per_page": 10,
  "total": 42,
  "pages": 5
}

Offset pagination, deliberately: the panel's tables are numbered, a total needs a count, and every table is scoped to one account so the offset never walks far.

Endpoints#

Authentication#

/api/auth/password/forgot always answers the same way whether or not the address exists, and login gives one reply for both an unknown address and a wrong password. Making either more helpful turns it into a way to enumerate accounts.

Account#

Domains#

The API token posted to dns/publish is used for that one call and never stored.

Addresses#

Filters#

/api/filters/validate is registered before /api/filters/:filter_id. The router matches in registration order and does not rank static segments above dynamic ones.

Transfers#

The source password is encrypted at rest and erased the moment the transfer reaches a terminal state.

Webhooks#

Listing shows only a prefix of the signing secret — enough to tell two apart. An endpoint that has lost its secret should rotate rather than read it back.

Billing#

Recovery#

Reached by mailbox owners who are not panel users at all, so it lives outside /app.

/api/recover/request answers identically whether or not the address exists.

Dashboard#

Webmail#

The address identity, via the corsair_webmail cookie. A 12-hour session.

Message bodies are sanitised server-side before this endpoint returns them.

Payment provider webhook#

Reads the body verbatim and verifies the signature before parsing.

Outside /api#

See JMAP.

Route ordering#

The router matches in registration order and does not rank static segments above dynamic ones. Two consequences worth knowing if you are extending it:

• /api/filters/validate must be registered before /api/filters/:filter_id
• addressRoutes is registered before domainRoutes so /api/domains/:domain_id/addresses is not swallowed by a domain pattern

src/api/index.ts documents the intended order.

Serialisation#

Every response shape comes from src/serialize. Keeping it in one place is what stops a secret gaining a field: a password hash, a DKIM private key, or a stored provider reference has to be added deliberately to be exposed, rather than appearing because someone returned a row.

Objects carry an object discriminator ("domain", "address", "webhook", "list") so a client can tell them apart without inspecting shape.