REST API

{
  "id": 48211,
  "uniqueId": "9d0b6b1e-…",
  "from": ["dana@arboretum.co"],
  "to": ["billing@yourdomain.com"],
  "cc": [], "bcc": [],
  "subject": "Invoice 2291 shows the old VAT rate",
  "body": "…",
  "isHtml": true,
  "received": "2026-09-05T07:14:02Z",
  "spamAction": "Deliver",
  "spamScore": 0.8,
  "spamSymbols": "HFILTER_HOSTNAME_UNKNOWN(2.5)"
}

The list endpoint and the message endpoints return the message's parsed body: HTML when the message had one, otherwise its text. Attachments are not exposed through the API.

spamAction is what the filter decided — Deliver, Junk, Defer or Reject — and spamSymbols lists the rules that fired, heaviest first, which is the answer to "why did this land in Junk". All three are null when nothing scanned the message: no filter reachable, or the message too large to scan. That is not the same as a clean verdict, and the difference is worth checking if you are acting on the field.

Parsed with a template

Add a template key to last or single, or pass template= to wait, and the message comes back with the values the template extracted instead of the raw subject and body. See Templates.

GET /messages/orders/order-confirmation/last

{
  "uniqueId": "…",
  "from": ["shop@example.com"], "to": ["orders@yourdomain.com"],
  "subject": { "order": "1048" },
  "body":    { "total": "€240.00" },
  "isHtml": false,
  "received": "2026-09-05T07:14:02Z"
}

Drafts

A draft written through the API is the same row as one written in the dashboard: it appears in the mailbox's Drafts folder, in the dashboard's Drafts view and in any IMAP client, from where a person sends it.

POST /messages/billing/draft
{
  "to": ["dana@arboretum.co"],
  "subject": "Re: Invoice 2291 shows the old VAT rate",
  "text": "Hi Dana, a corrected invoice is attached…",
  "html": null,
  "id": null
}

html takes precedence over text when both are given.

Sending

POST /messages/{key}/send sends now, from that mailbox's own address, and needs the mail:send scope. The message is recorded in Sent exactly as one sent from the dashboard is, so it appears in the thread, in the dashboard and in any IMAP client.

POST /messages/billing/send
{
  "to": ["dana@arboretum.co"],
  "subject": "Re: Invoice 2291 shows the old VAT rate",
  "text": "Hi Dana, a corrected invoice is attached…",
  "html": null,
  "cc": [],
  "bcc": [],
  "inReplyToMessageId": 48211
}

inReplyToMessageId is the id of the message being answered, as the read endpoints return it. Supply it unless the sending domain has been approved for writing to people who have not written first: without it such a send is refused with 403, which is the anti-abuse rule working rather than a fault. A 202 means the delivery provider has accepted the message.

There is no bulk endpoint and there will not be one: FounderMail hosts a team's mail, and transactional or marketing blasts belong with a service built for them.

Contacts

Attach your own record of a customer to the contact FounderMail keeps for their address, so it appears beside their mail in the dashboard.

PUT /contacts/{email}/link
{
  "externalUserId": "usr_8Kd21",
  "plan": "Pro",
  "monthlyRevenue": 290,
  "signedUpAt": "2025-03-14T09:00:00Z",
  "displayName": "Dana Kessler",
  "attributes": "{\"Seats\":\"12\"}"
}

DELETE /contacts/{email}/link

Every field is optional. attributes is a JSON object serialised as a string; its members are shown as extra rows under In your app. The response includes created, true when the address had never written to you and the contact was created by this call. Such a contact is not verified by inbound mail and does not make the address a permitted recipient in reply-only mode; see Contacts.

Templates

Status

GET /status returns 200 when the API is up. It requires a key like everything else.

Errors and limits

• 401: missing or unknown key.
• 403 with a missingScope field: the key lacks that scope. Check the key before checking the data.
• 404: the mailbox, message or template is not in your workspace. Ids from another workspace are not found rather than forbidden.
• 429: the plan's request rate was exceeded (Free: 20 a minute, 100 an hour; Plus: 40 a minute, 300 an hour; Pro: 60 a minute, 1,500 an hour; Scale: 200 a minute, 10,000 an hour). Back off and retry.
• Other errors are returned as problem details with a title and detail.