API reference

Use Agentic Inbox to connect a mailbox to an assistant, or the management API to administer your organisation’s domains, mailboxes and aliases. These use separate credentials and permissions. Choose the integration you need below.

Agentic Inbox

Connect through OAuth with PKCE at https://franklymail.com/api/agent/mcp. The connection guide covers ChatGPT and Claude setup. Sign in to webmail. Each OAuth grant is bound to that one verified mailbox. Grants use mailbox.read, message.read, message.search and draft.write. There is no automatic sending permission.

Drafts return a review link. Only a session verified for that mailbox can approve the exact current version. A panel account session cannot consent or approve. Tool arguments or a chat message cannot authorize sending.

For folder-specific searches, pass folder as inbox, sent, drafts, archive, trash or junk (spam is an alias). Use list_folders and folderId for custom folders. Choose one selector; a missing folder returns an error instead of searching all mail. Omitting both searches every folder.

prepare_forward requires mailboxId, messageId, requestKey and to; cc and introductory text are optional. It requires both message.read and draft.write. Original headers and readable text are included automatically. Attachments require webmail, or the user's explicit choice of text only using omitAttachments: true. Incomplete or oversized originals are rejected. Forward drafts use the same review and approval flow as replies.

The human review page supports editing recipients, subject and message. Mailbox Boost also adds optional Track opens and Write with AI. Tracking is off until selected and saved. A shared message sent to several recipients cannot identify which recipient opened it. Privacy proxies can affect open signals; view activity in webmail.

The AI writer requires mailbox consent and shares the webmail writing allowance. It uses the saved draft, subject, recipients and writing instructions to prepare a suggestion through OpenAI. Applying a suggestion is an edit, followed by save and a fresh human approval. Neither feature adds an MCP tool or a sending permission; agents cannot set trackOpens or call the browser writer.

OAuth uses authorization code with S256 PKCE and resource=https://franklymail.com/api/agent/mcp. Discover configuration at the protected resource metadata and authorization server metadata. Dynamic client registration is supported. Access tokens last one hour; refresh tokens rotate. Reusing a refresh token revokes the connection. Grants last up to 90 days.

MCP uses stateless Streamable HTTP with JSON responses. Call tools/list for schemas. Successful calls include result.structuredContent; tool failures may return HTTP 200 with result.isError=true and a JSON text block containing error. Check both the HTTP response and tool result. Authentication failures use HTTP 401.

Equivalent HTTP routes: GET /api/v1/mailboxes/:id/messages, GET /api/v1/mailboxes/:id/messages/:messageId, POST /api/v1/drafts, GET /api/v1/drafts/:id and PUT /api/v1/drafts/:id. Search accepts folder or folderId, text, from, subject, unread, limit (1 to 25) and position. Draft creation requires mailboxId, requestKey, to, subject, text; cc and replyToMessageId are optional. Revision requires the current version and complete replacement recipients, subject and text.

Folder listing and forwarding use the MCP tools list_folders and prepare_forward; they do not have separate HTTP routes. Drafts support at most 10 To and Cc recipients combined, a 256-character subject and 20,000-character message, and expire after 24 hours. They stay in Agentic Inbox until approved; sent messages appear in webmail.

Agentic Inbox allows 25 requests/day and 5/minute per mailbox; Boost raises this to 2,500/day and 60/minute. Connections to the same mailbox share its allowance. Password changes revoke mailbox sessions and connections. Existing account-authorized inbox grants must reconnect through webmail. Daily allowances reset at midnight UTC. Manual review and approval do not use this allowance. On a limit error, respect Retry-After and error.resetsAt; show the supplied Boost link on standard-plan exhaustion.

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.

There is no mailbox-count quota to enforce that distinction. If an account grows a shape that reads as several organisations, we write and ask. Nothing is suspended over a question.

Legacy resource API: metadata only

Existing resource credentials keep their original permissions. To enable mail content access, create a new connection using the assistant connection guide. Keys granted only domain.read and mailbox.read read metadata only. They cannot read messages, send mail or change resources. Newly created mailboxes and domains never gain access automatically.

Send the key as Authorization: Bearer fma_.... Paths below are relative to https://franklymail.com/api.

Lists accept limit from 1 to 100 (default 50) and a UUID cursor from the preceding response. They return { data: [...], nextCursor, requestId }; details return { data: {...}, requestId }. Byte counts are decimal strings. DNS results are stored observations.

Standard restricted access allows 25 requests/day and 5/minute, shared across the account's keys. Mailbox Boost raises this to 2,500/day and 60/minute per subscribed mailbox. Days reset at midnight UTC. Key ceilings default to 60/minute, adjustable from 1 to 600, with a separate shared account safety ceiling of 600/minute.

Each returned Boost mailbox uses one request from its own allowance. Any standard resources on the page share one standard request. All required allowances must be available; a rejected page spends none of them. An empty page uses the standard allowance. Domain and DNS reads can use the allowance of the first Boost mailbox by UUID in that domain, only when the key explicitly grants mailbox.read for it too. This does not increase access to other mailboxes.

On 429, honor Retry-After and error.resetsAt. Daily exhaustion uses daily_quota_exceeded; minute limits use rate_limited. Standard plan limits include error.metadata.upgrade with the Boost link and higher allowances. Show that link to the person managing the mailbox. An agent cannot purchase an upgrade. Boost exhaustion and key/account safety ceilings have no upgrade offer. X-Agent-Plan identifies standard, boost or mixed access; X-Agent-Daily-Limit, X-Agent-Daily-Remaining and X-Agent-Daily-Reset describe the required daily allowance with the fewest requests left. Key ceilings still count authenticated denials. Missing scope returns 403; a resource outside the grant returns 404; an expired or revoked key returns 401. Restricted credentials work on /api/v1 and /api/agent/mcp within their original scopes. Those routes accept neither browser cookies nor management keys.

Management API authentication

Choose “New management 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 management 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, since 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, and 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.

What that boundary does not claim. A key can set a mailbox password, because creating and handing out mailboxes is the job it exists for, and anyone who can set a mailbox password can then sign in to that mailbox over IMAP and read it. Closing export does not change that, and pretending otherwise would be a worse kind of security than none. What it does change is that the path is no longer silent: resetting a password locks the real user out of their own mailbox, which is noticed within the hour, while a download leaves nothing behind but a log line. If that trade is not the one you want for a particular key, do not create the key: management keys have no per-resource scopes. Use an Agentic Inbox OAuth connection for a mailbox verified through webmail.

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

Changing the account password revokes every key, on a routine rotation as much as on a recovery. Nobody can tell those two apart at the moment they type a new password, so the safe answer does not depend on knowing which it was. Plan for it: a long-running script should fail loudly on a 401 rather than retry, and whoever rotates the password mints a new key afterwards. We email the account holder whenever a key is created, and again when a password change revokes them, so a key made by someone else does not go unnoticed.

Management API and export 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, since 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

Agentic Inbox provides the remote MCP endpoint at https://franklymail.com/api/agent/mcp for mailbox reading, searching and draft preparation. Connect through OAuth using the setup guide. Domain provisioning and mailbox administration use the separate management HTTP API documented above.