API endpoints

Endpoints

The /api/v1/* and /health endpoints are served by the SDK backend at sdk.flowmails.net; anything outside them returns plain-text Not Found (404). The /api/agent/* endpoints are served by the same host as /api/v1/* — the agent platform moved to the SDK backend — and both accept the same fm_ key.

Scoped credentials

A credential comes in two shapes. The fm_ key is the one this documentation has always described: tenant-wide for reads and bound to one domain for sends, revocable in one click. The agc_ credential is the narrowed one — you issue it in Settings → Agent Credentials, tick only the capabilities the agent needs, and the platform refuses anything else with a typed { error: "scope_denied", required } (403). The raw key is shown once, at issuance; only its SHA-256 hash is stored, and revoking it takes effect immediately on every agent route.

The scope matrix is nine names: events:read, waits:read, waits:write, messages:read, messages:search, messages:send, send_status:read, addresses:read and addresses:write. A scope says which tools an agent may call — it is never an approval gate. Flowmails does not ask a human before the agent sends.

The MCP server

A hosted Model Context Protocol server answers POST /mcp on sdk.flowmails.net over streamable HTTP. It accepts the same two credential types, and every tool checks the credential’s scope before it runs.

Ten tools, deliberately: every extra tool is a way for an untested agent to change account configuration by accident. The same capabilities are also reachable through @flowmails/flowmails-sdk and the flowmails CLI.

Request body

The JSON below is what the SDK backend receives. The SDK re-shapes your typed SendOptions into this exact shape, so you shouldn’t need to read or build this JSON directly.

{
  "from": "support@yourdomain.com",
  "fromName": "Support",                       // optional — display name
  "to": ["customer@example.com"],               // string or string[]
  "perRecipient": true,                         // optional — one message per recipient (default)
  "replyTo": "noreply@yourdomain.com",          // optional — Reply-To header
  "replyToMessageId": "<abc@example.com>",      // optional — reply in thread
  "idempotencyKey": "order-1234-attempt-1",     // optional — dedupe a retry
  "subject": "Order #1234 confirmed",
  "text": "Plain text body",                    // optional but at least one
  "html": "<p>HTML body</p>",                   // optional but at least one
  "attachments": [                              // optional
    {
      "filename": "invoice.pdf",
      "content": "JVBERi0xLjQKJ...",            // base64 OR raw string
      "mimeType": "application/pdf"
    }
  ]
}

Constraints enforced by the handler before the request ever leaves the SDK backend:

• from must be a valid RFC 5322 address and must land on the domain bound to the API key. A mismatch returns from_domain_mismatch (422).
• idempotencyKey is optional and scoped to your account. With it, a retry replays the first answer instead of sending twice; the same key with adifferent payload answers idempotency_key_conflict (409). Without it, every call sends.
• The send is counted against a quota — per account and per domain, per hour and per day. Exceeding it answers rate_limit_exceeded (429) with limit, remaining and resetAt, plus the X-Flowmails-RateLimit-Remaining/ X-Flowmails-RateLimit-Reset headers and Retry-After. The send is refused before it is dispatched.
• Every to recipient must be a valid email address.
• subject must be 1..998 characters.
• At least one of text or html must be a non-empty string. Each body is capped at 1,000,000 characters.
• The local-part of from must be 1..64 characters. The receive-worker does the route-table validation downstream.
• replyToMessageId is the parent’s SMTP Message-ID (or its row id). The backend reads that row and derives In-Reply-To, References and the thread anchor — you never build those headers. A parent outside the key’s bound domain is reply_parent_not_found (404); a parent whose sender stripped the Message-ID is reply_parent_unthreadable (422).

Response

On success the SDK backend returns the message id with HTTP 201. The id is the numeric email.id row id from the receive-worker, stringified for JSON safety; messageId is the SMTP Message-ID the relay assigned — the key every read path takes.

HTTP/1.1 201 Created
Content-Type: application/json

{
  "id": "8421",
  "status": "sent",
  "messageId": "<abc123@yourdomain.com>",
  "sendFeedback": null,
  "error": null,
  "recipients": [
    {
      "to": "customer@example.com",
      "id": "8421",
      "status": "sent",
      "messageId": "<abc123@yourdomain.com>"
    }
  ]
}

Several recipients? Each one gets its own message by default — they cannot see each other, and one refused address does not hold up the others. status is then the verdict over all of them: "sent", "partial" (some were refused) or "failed", and recipients says what happened to each address — its row id, its own verdict and the relay’s reason when it was refused. error is "send_failed" for a partial send too: check it before treating a 201 as “sent”. Send one shared envelope to everybody instead with perRecipient: false — one message, one bill from a provider that charges per message, and then the send is all-or-nothing by construction.

Follow the send with GET /api/v1/messages/:id (fm.messages.status()): it returns sent (the relay accepted it) or failed (the relay rejected it), the relay’s error string in sendFeedback and the error slug beside it. A bounce is not observable — the status vocabulary holds delivered / bounced, but the receive worker has no bounce ingestion and never writes them. Push webhooks are shipped, for a message arriving and for a message being sent; the delivery-status half is not. The complete error envelope is documented on the Errors page.

Field renames between the SDK and the wire

The SDK keeps html as the body field name (it’s what email-library users expect), and the SDK backend re-shapes it to content when it forwards to the receive-worker’s /api/email/send. The attachments binary encoding and the single-recipient wrap happen entirely inside the SDK before the request leaves.

What the SDK does for you

• JSON encoding. The SDK JSON.stringifys the body and sets Content-Type for you.
• 15-second timeout. AbortSignal.timeout(15_000) matches the SDK backend’s upstream timeout, so you get UpstreamError rather than a generic 502 if the request stalls.
• Auto-retries. The SDK retries 5xx, 408 and network failures with exponential backoff (capped at 4 s) up to maxRetries (default 2). The one 429 it retries is idempotency_key_in_progress — a retry there replays the first answer rather than sending twice. The send quota’s 429 is not retried: the window is an hour, and a retry would burn another slot. Other 4xx is never retried — see Errors.
• Request id. If you set requestId on the constructor, every outbound request carries X-Flowmails-Request-Id for cross-stack tracing.

Reading and waiting

Inbound mail is durable platform state, not a long-poll. Every accepted message lands in an event log you read with a cursor, and a wait you open (and which answers immediately) is resolved for you when a matching message arrives. Neither suspends a request: an edge request dies long before a verification mail lands, so the state lives on the platform and you poll it.

The event is routing facts plus the subject — { messageId, event, recipient, sender, subject, createdAt } — and never a body. The content is an explicit ask (fm.messages.get(messageId)), which is why an agent is never handed a message it did not want.

import { Flowmails } from "@flowmails/flowmails-sdk";

const fm = new Flowmails({ apiKey: process.env.FLOWMAILS_API_KEY! });

// 1. Open a durable wait. Returns immediately.
const wait = await fm.waits.create({
  address: "billing@yourdomain.com",
  subject: "invoice",        // optional substring constraint
});

// 2. Poll the platform — you can stop and resume; it is durable state.
let status = wait;
while (status.status === "pending") {
  await new Promise((r) => setTimeout(r, wait.pollAfterMs));
  status = await fm.waits.get(wait.waitId);
}

// 3. Fetch the body explicitly.
if (status.status === "resolved" && status.resolvedMessageId) {
  const mail = await fm.messages.get(status.resolvedMessageId);
  console.log(mail.text);
}

A wait is a shortcut, not the record: a message that lands one second after the deadline does not resolve the wait, but it is in the event log. An agent that only waits will eventually miss one; an agent that reads fm.events.list({ after }) cannot. Use both when it matters.

Creating the mailbox in the first place is fm.addresses.create(domainId, "billing") — idempotent, and the only account-configuration write the agent surface has. Mode changes, bulk edits, route templating and unbinding stay dashboard-only.