The Flowmails SDK
A typed JavaScript client for the Flowmails platform. Send transactional and operational email from your own domain, wait for the reply, read it, create the mailbox it lands in, and point a signed webhook at a URL you control — auth via a Bearer SDK key pinned to one of your domains.
Sections
What’s in the SDK today, and what’s next
Each section carries a version badge so you know whether the surface is shipped or still on the roadmap. The status badges on this page are the single source of truth for what SDK callers can rely on — when a feature lands, both the corresponding card here and its target page update in the same PR.
Install & Quick start
Add @flowmails/flowmails-sdk to a Node project and ship your first transactional message in under five minutes.
API endpoints
POST /api/v1/messages, GET /api/v1/messages/:id, and the agent read/wait/address endpoints, plus the SDK ↔ wire field renames (html → content, base64 attachments).
Errors & retries
The full error matrix, the FlowmailsError class hierarchy, and the retry policy — which failures are retried, and which are not.
Integrate with AI agents
Install the flowmails-sdk skill into your AI agent and ship a working @flowmails/flowmails-sdk integration in one prompt.
The flowmails CLI
Drive the same capabilities from a shell: check the connection, list mailboxes, tail inbound mail as JSON lines, and wait for a message — with a cursor that survives a disconnect.
Webhooks
Point Flowmails at a URL you control and it will POST to it, signed, when a message arrives or is sent — with a delivery log, automatic retries and an SSRF guard on every attempt.
v1.0 roadmap
Delivery-status webhooks land in the next milestone, on top of the signed delivery that already ships. Wire shapes are drafts.
What’s still on the roadmap
- Delivery-status webhook events — roadmap, not shipped: the signed webhook fires when a message arrives and when one is sent, but the delivered and bounced half needs the receive worker to report its status transitions — it has no bounce or DSN ingestion today, so a bounce is not observable at all. A send’s status is sent or failed.
Ready to send
Verification and password-reset mail through @flowmails/flowmails-sdk — the four callbacks, both email templates, and the seven behaviours in that surface that fail silently.