Install & Quick start

The SDK is a thin, dependency-free TypeScript client. One constructor, one method, one wire endpoint. Five minutes from pnpm add to a delivered transactional message — no SMTP server, no API token rotation, no per-request signing ceremony.

1. Install the package

The SDK is published as @flowmails/flowmails-sdk on npm. The package carries zero runtime dependencies — it uses the platform-native fetch and Uint8Array, so it runs in Node 18+, Workers, Bun, Deno, and the browser without a polyfill.

terminalbash

pnpm add @flowmails/flowmails-sdk
# or
npm install @flowmails/flowmails-sdk
# or
yarn add @flowmails/flowmails-sdk

2. Mint an API key

API keys live in the Flowmails dashboard under Settings → API Keys. Every key is pinned to one of your registered domains — the SDK backend rejects any send() call whose from address doesn’t land on that bound domain, so a compromised key can’t impersonate addresses on your other domains.

The dashboard shows the raw key exactly once, immediately after minting. Store it in your secrets manager; we don’t keep a recoverable copy on the server side.

3. Send your first message

Construct a client with your API key and call send(). The result is the queued message id you can correlate with the row that eventually lands in the user’s dashboard inbox.

send.tsts

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

const fm = new Flowmails({
  apiKey: process.env.FLOWMAILS_API_KEY!,
  // baseURL: "https://sdk.flowmails.net",  // default — override for staging
});

const result = await fm.send({
  from: "support@yourdomain.com",
  to: "customer@example.com",
  subject: "Order #1234 confirmed",
  text: "Thanks for your order — we'll ship it tomorrow.",
  // html: "<p>Thanks for your order…</p>",  // optional — at least one of text/html
});

console.log(result); // { id: "msg_8421", status: "queued" }

4. Constructor options

The Flowmails constructor accepts four fields. Only apiKey is required.

Option	Type	Notes
apiKey	string	Required. fm_<32+hex> issued in the dashboard.
baseURL	string	Defaults to https://sdk.flowmails.net. Override for staging / private-region deployments.
maxRetries	number	Auto-retries on transient 5xx / 408 / 429. Defaults to 2. Set to 0 to disable. See Errors.
requestId	string	If set, the SDK sends X-Flowmails-Request-Id on every request for cross-stack tracing.
fetch	typeof fetch	Inject a fetch implementation (Workers environments, test harnesses). Defaults to the global.

5. What gets stored where

The SDK only holds the API key in memory for the lifetime of the Flowmails instance. There’s no disk persistence, no environment variable capture, no logging of the key. Logs from the SDK are limited to request ids and HTTP statuses — never payloads, never headers, never the bearer token.

The receive-worker (downstream of the SDK backend) writes the outbound row to your D1 under the bound domain’s account, so the message appears in the dashboard inbox with type === "send" and is filterable alongside inbound mail.

Next up

API reference Errors & retries