Self-hosted · CFFlowmails

Docs / Roadmap

Planned for v0.2

v0.2 roadmap

The next milestone rounds out the SDK into something you can build a real product on top of: reads, async delivery notifications, and self-throttling. None of these wire shapes are committed yet — treat them as drafts and pin us in the dashboard changelog when they ship.

These items are subject to change as the milestone hardens. When a feature lands, this page (and the matching /docs/* page that owns the detail) move together in the same PR.

Draft

messages.list & messages.get

Read endpoints that mirror what the dashboard inbox already shows. SDK callers can pull their own sent / received mail without scraping the dashboard.

  • List messages by mailbox localpart, paginated, filterable on status (queued, sent, bounced).
  • Single message lookup by id returns the full row including attachments metadata.
  • Field renames stay consistent — SDK uses SendOptions-style names, backend normalises to the wire.
// Proposed
GET /api/v1/messages?localpart=support&status=sent&limit=50
GET /api/v1/messages/{id}

// Response
{ "messages": [Message], "nextCursor": "..." }
Draft

threads.get

Conversation-level read. Threads group every email that shares a root message-id, across both inbound and outbound rows.

  • Resolves a threadId (root message-id) to the full conversation chain.
  • Returns ordered list with threadPosition for client-side grouping.
  • Useful for support tooling — show the whole ticket in one call.
// Proposed
GET /api/v1/threads/{threadId}

// Response
{
  "threadId": "msg_8421@yourdomain.com",
  "messages": [{ id, from, to, subject, status, threadPosition, ... }]
}
Draft

Outbound webhook delivery

A signed HTTP POST to a URL you control on every queued → sent → bounced lifecycle event. HMAC-SHA256 signature in the X-Flowmails-Signature header.

  • Configure the webhook URL per API key in the dashboard.
  • At-least-once delivery with automatic retry (exponential backoff up to 24 h).
  • Replay log: every delivery attempt is queryable for 30 days.
  • v0.2 ships the events table; signing key management lands in v0.2.1.
// Proposed payload
POST <your-webhook-url>
Content-Type: application/json
X-Flowmails-Signature: sha256=<hex>
X-Flowmails-Event: message.sent

{
  "id": "msg_8421",
  "event": "message.sent",
  "delivered_at": "2026-07-06T12:34:56.000Z",
  "message": { ... }
}
Draft

Per-key rate-limit headers

Today every 429 is the platform safety floor. v0.2 surfaces your real quota via X-Flowmails-RateLimit-Remaining and X-Flowmails-RateLimit-Reset so clients can self-throttle cleanly.

  • Headers echo on every authenticated response, not just 429.
  • Reset header is a Unix timestamp; remaining is the integer count after this request.
  • Client-side backoff becomes deterministic instead of guess-and-check.

What v0.2 is not

  • Marketing email platform. Flowmails is built for transactional and operational mail, not bulk campaigns.
  • Full-text search. v0.2 lists by localpart and status; freeform search across message bodies ships later (likely v0.3).
  • Per-key webhook signing rotation. v0.2 ships the signing key generated at mint time; rotation lands in v0.2.1.

Ship today

Back to installMint an API key