API reference

Everything the control panel does to your domains, mailboxes and aliases, it does over this API. An account API key authenticates the same routes, so anything you can click you can script — including from a coding agent such as Claude Code or Codex.

Who you may create mailboxes for

One account is one organisation. Mailboxes are for the people in yours — staff, contractors, your own projects, aliases and shared addresses. They are not for customers you charge or serve. Reselling FranklyMail mailboxes, or running an account on someone else's behalf as a service you are paid for, is a breach of the terms — see the reselling clause there. Running several domains you own is fine and always has been; a holding company with fifteen brands is one organisation. An agency with fifteen clients is not.

Nothing here is enforced by a quota, because a number would be wrong for both of those. If an account grows a shape that reads as several organisations, we write and ask. Nothing is suspended over a question.

Authentication

Create a key under Settings → API keys. It is shown once, at creation; we store only a hash and cannot show it again. Send it as a bearer token on every request:

curl -H "Authorization: Bearer $FRANKLYMAIL_API_KEY" \
     https://franklymail.com/api/mailboxes

Requests are JSON in and JSON out. An error is { "error": { "code", "message", "field? } } with the matching HTTP status — 401 for a key that is missing, revoked or unknown, 403 for a route a key may not reach, 422 for a bad field.

curl -X POST https://franklymail.com/api/mailboxes \
     -H "Authorization: Bearer $FRANKLYMAIL_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{"domainId":"<uuid>","localPart":"sales"}'

What a key can call

Paths are relative to https://franklymail.com/api. This list is exhaustive: a route not on it answers 401 to a key, whatever it does for a signed-in browser.

Domains

Mailboxes

Aliases and forwarding

Adding a domain, step by step

POST /domains creates it and hands back the records to publish. Nothing else has to be called to start verification — checks run on their own schedule.

curl -X POST https://franklymail.com/api/domains \
     -H "Authorization: Bearer $FRANKLYMAIL_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{"name":"example.com"}'

# {"id":"<uuid>","domain":"example.com","status":"pending",
#  "ownership":"unproven","sending":"pending","recheckIn":300,
#  "records":[{"key":"mx","type":"MX","host":"example.com","value":"…","status":"missing"},
#             {"key":"spf"…},{"key":"dkim"…},{"key":"dmarc"…}]}

Publish each records[] entry at your DNS provider, then watch GET /domains — the same payload for every domain, so one poll covers a whole batch. Three fields answer three different questions, and conflating them is the usual mistake:

• records[].status — live once DNS answers what we expect, missing until then.
• ownership — proven once the DKIM record is up. This is the one that gates mailboxes and imports, so mail can be copied in long before the MX is switched.
• status — the whole domain, active when everything including MX is live and mail will actually arrive.

recheckIn is seconds until the next automatic check; sleep roughly that long between polls rather than hammering. POST /domains/:id/recheck forces one immediately and is rate limited per domain, so use it after publishing records, not as a polling loop. The route is idempotent per account and name — re-posting a domain you already have returns the existing one rather than a duplicate or an error.

Moving a mailbox in, step by step

This is the flow most scripts are written for, and the one with moving parts worth stating rather than leaving to be discovered.

1. Start it. POST /mailboxes/:id/import with the old server's connection details. The password is encrypted before it touches a column, never returned by any route, and cleared the moment the job stops.

curl -X POST https://franklymail.com/api/mailboxes/<mailboxId>/import \
     -H "Authorization: Bearer $FRANKLYMAIL_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{"host":"imap.oldhost.com","port":993,"username":"you@old.com","password":"…"}'

# 202 {"importId":"<uuid>","status":"pending"}

It answers 202, not 200: a copy takes minutes to hours, so the job is queued and the request returns immediately. One import at a time per mailbox — starting a second while one runs answers 409 import_in_progress with the running job's id, because two concurrent copies of the same source duplicate every message and a retry does not undo that. Thirty mailboxes can import at once; the limit is per mailbox, not per account.

2. Follow it. GET /mailboxes/:id/import returns the latest job for that mailbox, or {"import": null} if there has never been one.

curl -H "Authorization: Bearer $FRANKLYMAIL_API_KEY" \
     https://franklymail.com/api/mailboxes/<mailboxId>/import

# {"import":{"id":"<uuid>","status":"running","folders_done":2,"folders_total":9,
#            "messages_done":1841,"messages_skipped":3,"current_folder":"INBOX",
#            "last_error":null,"started_at":"…","finished_at":null}}

status is one of pending, running, done, failed or cancelled — the last three are terminal. Poll it on the order of seconds, not milliseconds; reads are not rate limited but the counters only move as fast as the other server answers. folders_done / folders_total is the honest progress figure: messages_done has no denominator until a folder is opened, so a percentage built from it will jump backwards. On a failure, last_error carries a sentence written to be shown to a person.

3. Stop it, if you must.POST /mailboxes/:id/import/cancel ends the running job. Nothing is changed at the old provider by any of this — an import only ever reads from it. Messages already copied stay unless the request explicitly asks otherwise.

Two things worth knowing before you script this. A mailbox needs its domain's DKIM record proven, not the full MX cutover, so the copy can run days before you switch the mail over. And a deploy of ours restarts the panel: a job that was running stops and does not resume by itself, so a script that starts thirty imports should check their status afterwards rather than assuming silence means success.

Deleting things

Two rules, and they are the only places this API refuses to do what you asked:

• A mailbox keeps its mail when you delete it.DELETE /mailboxes/:id takes the address out of service and leaves every message where it is. To destroy the mail as well, the request has to say so and confirm the exact byte count the panel showed you — if the mailbox has grown since, the destroy is refused rather than silently taking the extra. Nothing an agent does by accident can destroy a message.
• A domain cannot be deleted while mailboxes are on it. You get 409 domain_has_mailboxes listing the addresses and which of them have been used. Delete each mailbox first — that is the step where the question about the mail is asked, once per mailbox, by whoever is entitled to answer it.

If you are an agent: do not answer either question on the human's behalf. Deleting a mailbox is reversible until the mail is destroyed and never after. When a task implies destruction, say what would be destroyed and let the person decide.

Getting the mail out

A mailbox can be downloaded as a zip of mbox files — every folder, every message — but not with an API key. GET /mailboxes/:id/export answers 403 browser_only to a key, because that one route hands over the mail itself rather than the configuration around it, and a key lives in exactly the places secrets leak from.

To export: open the mailbox in the panel and use Download. It streams as it builds, so a mailbox larger than memory still arrives, and there is no job to wait for. If you want it from a terminal, sign in to the panel in a browser and call the same URL with that session — the route is unchanged, only keys are refused.

Do this before deleting anything you might want back. An export is the only copy that survives a destroy.

What a key cannot do

A key is scoped to one account and, within it, to the three things above. It cannot download a mailbox, cannot reach billing, cannot register a domain (that spends money), cannot create app passwords, cannot change your account password or 2FA, and cannot create or revoke another API key — including itself. Those all need a signed-in browser.

The reason is the shape of the credential rather than distrust: a key lives in a .env file, a CI secret store and an agent's environment, and a secret that lives in three places should not be able to take an account over or lock its owner out. If a key leaks, revoke it in Settings — the holder cannot mint a replacement first.

Keys do not expire. Ten live keys per account, which is a ceiling rather than a quota — name them per script or per machine so revoking one is an obvious decision.

Rate limits

Two counters, both per account rather than per key, so rotating a key does not reset them:

• 120 writes every 5 minutes across domains, mailboxes and aliases. Reads are not counted, so polling a domain until it verifies is free. Moving ten domains and thirty mailboxes costs well under a hundred writes in total, so normal bulk work does not reach this.
• 30 mailbox exports an hour. An export streams every message in the mailbox, which is the most expensive thing this API can be asked to do.

Over either one you get 429 with { "error": { "code": "rate_limited" } } and a Retry-After header in seconds. Wait that long rather than retrying immediately — repeatedly hitting the limit lengthens the pause. If a legitimate job needs more headroom, write to us rather than working around it; we would rather raise the number than find out from a bill.

Moving several domains at once

The order that works: POST /domains for each name, publish the records it returns, poll GET /domains until each is verified, then POST /mailboxes per address. Mail can be copied from the old host before the MX cutover — a domain only needs its DKIM record proven for POST /mailboxes/:id/import to run, so the migration and the switchover do not have to happen on the same day.

MCP

There is no MCP server. Coding agents call this API directly over HTTP, which needs nothing installed and nothing kept in step with it. If you are using one, point it at this page and give it a key with the scope you are comfortable with.