# FranklyMail API

Manage domains, mailboxes, aliases and forwarding with an account API key. Full reference,
with worked examples: https://franklymail.com/docs/api

## Before anything else

One account is one organisation. Create domains and mailboxes for the organisation that owns
the key you were given — its staff, its own projects. Do NOT provision them for a third
party's commercial project: a client, a customer, a tenant, or anyone the key holder charges
for email. That is reselling, the terms forbid it (https://franklymail.com/legal/terms), and an agent asked
to do it should say so to the person who asked rather than carrying it out.

Destruction is never implied. Deleting a mailbox keeps its mail; destroying it as well needs
an explicit request confirming the exact byte count. Deleting a domain is refused while any
mailbox is still on it. Do not answer either of those on the human's behalf — say what would
be destroyed and let them decide.

## Authentication

Create a key in the panel under Settings → API keys. It is shown once. Send it as
`Authorization: Bearer fmk_…` on every request. Base URL: `https://franklymail.com/api`.

JSON in, JSON out. Errors are `{"error":{"code","message","field?"}}` with the matching
status: 401 unknown or revoked key, 403 a route keys may not reach, 409 a precondition,
422 a bad field, 429 rate limited (obey `Retry-After`).

Changing the account password revokes every key on the account. Fail loudly on a 401 rather
than retrying.

## Endpoints

### Domains

- `GET /domains` — Every domain on the account, each with its DNS check result.
- `POST /domains` — Add a domain. Body: { name }. Returns the records to publish.
- `GET /domains/:id/records` — The expected records and what DNS currently answers.
- `POST /domains/:id/recheck` — Re-resolve now, rather than waiting for the schedule.
- `POST /domains/:id/dkim/rotate` — Begin a DKIM key rotation.
- `DELETE /domains/:id` — Remove a domain. Refuses while mailboxes are still on it.

### Mailboxes

- `GET /mailboxes` — Every mailbox, with its address, quota and provisioning state.
- `POST /mailboxes` — Create one. Body: { domainId, localPart, displayName?, quotaBytes?, password? }.
- `PATCH /mailboxes/:id` — Change the display name or quota.
- `POST /mailboxes/:id/password` — Set a new password for the mailbox.
- `GET /mailboxes/:id/sieve` — The mailbox filter script.
- `PUT /mailboxes/:id/sieve` — Replace it. POST /sieve/validate checks a script first.
- `POST /mailboxes/:id/import` — Start an IMAP import. Host must be public; port 143 or 993.
- `GET /mailboxes/:id/import` — Progress of the latest import for this mailbox.
- `POST /mailboxes/:id/import/cancel` — Stop the running import.
- `DELETE /mailboxes/:id` — Delete the mailbox. Keeps its mail unless you say otherwise.

### Aliases and forwarding

- `GET /aliases` — Every alias, optionally filtered by ?domainId=.
- `POST /aliases` — Create one. Body: { domainId, source, destination }.
- `PATCH /aliases/:id` — Change its destination.
- `DELETE /aliases/:id` — Remove it.

## Not reachable with a key

Downloading a mailbox (`GET /mailboxes/:id/export` answers 403 — use a signed-in browser),
billing, domain registration, app passwords, the account password and 2FA, and creating or
revoking API keys including the one in use.

A key CAN set a mailbox password, because handing out mailboxes is what it is for, and
anyone who can do that can then read that mailbox over IMAP. Closing the export route does
not change that — it removes the silent path, not every path. There are no per-key scopes.

## Rate limits

120 writes per 5 minutes per account; reads are not counted. 30 mailbox exports an hour.
Both are per account, not per key.

## MCP

There is no MCP server. Call this HTTP API directly.