The Postboi provider

The zero-config way to send. No provider account, no DNS records, no card: run one command, authorise in the browser, and mail() works.

bunx postboi init

bunx postboi init

npx postboi init

npx postboi init

pnpm dlx postboi init

pnpm dlx postboi init

yarn dlx postboi init

yarn dlx postboi init

Pick Postboi when prompted. The CLI opens your browser to authorise the device, then writes a single env var: POSTBOI_TOKEN, your API key (keep it secret). Everything else is config, not environment: it offers to set defaults (to, reply_to, cc, bcc, and from, once you have custom domains to choose between) and writes them to a committed postboi.config.ts, the same file where you can add hooks later. The CLI knows your domains and their verification status, so it won’t accept a default from at a domain that isn’t on your account (listing the ones that are), and warns when the domain is still pending verification.

Re-running init is safe: when a working POSTBOI_TOKEN is already in your environment it’s reused rather than replaced, so you can walk through the CLI again any time to revisit your defaults.

That’s the whole setup:

import { mail } from "postboi"

await mail({
	to: "someone@example.com",
	subject: "Hello",
	body: "<p>Sent through the Postboi provider</p>",
})

import { mail } from "postboi"

await mail({
	to: "someone@example.com",
	subject: "Hello",
	body: "<p>Sent through the Postboi provider</p>",
})

from is optional: when omitted entirely, the API uses your account’s sending address, which the token identifies. Env vars still override config for per-environment tweaks (POSTBOI_FROM beats default.from), but nothing needs to live in the environment except the token.

The Postboi provider also includes managed invisible captcha for your forms: one script tag from the dashboard, no Cloudflare account, no keys. See Spam protection.

Your sending address

Free-tier mail goes out from you@send.postboi.email, derived from your signup email. It’s a real, deliverable address on our reputation-managed sending domain. Set reply_to when you want responses to go straight to a particular inbox:

await mail({
	to: "someone@example.com",
	reply_to: "you@yourdomain.com",
	subject: "Hello",
	body: "<p>Replies come to you</p>",
})

await mail({
	to: "someone@example.com",
	reply_to: "you@yourdomain.com",
	subject: "Hello",
	body: "<p>Replies come to you</p>",
})

You can rename the address (once a day) from the dashboard.

Replies

Your sending address is also a mailbox. Anything sent to it — including a reply to a message that never set reply_to — lands in Messages → Received in the dashboard, with the body, the sender, and a link back to the send it answers.

That happens whether or not you configure anything. Two things you can add on top:

• Forward to your own inbox. On the dashboard overview, under Replies, give an address and click the verification link Cloudflare emails it. From then on replies arrive in your normal inbox as well as the dashboard. (Replying from there goes out from your own address, not your Postboi one.)
• Handle them in code. Subscribe a webhook to email.received and each reply arrives as a normalized received event — the basis for a support inbox, a reply-to-confirm flow, or ticket creation.

Plus-tags route to the same mailbox, so you+order-1234@send.postboi.email is a per-thread address you can hand out and match on the way back:

await mail({
	to: "someone@example.com",
	reply_to: "you+order-1234@send.postboi.email",
	subject: "Your order",
	body: "<p>Just reply to this email</p>",
})

await mail({
	to: "someone@example.com",
	reply_to: "you+order-1234@send.postboi.email",
	subject: "Your order",
	body: "<p>Just reply to this email</p>",
})

Inbound is free on every plan. Mail to an address nobody owns is rejected rather than swallowed, and inbound HTML is sanitised before it’s stored.

Custom domains are outbound-only for now: pointing your domain’s MX at us would take over your real mail, so inbound stays on send.postboi.email.

Sending from your own domain

Verify a domain in the dashboard: add a domain, publish the three DKIM CNAME records it shows you, and hit Check. Once verified, any address at that domain is a valid from:

await mail({
	from: "hello@yourdomain.com",
	to: "someone@example.com",
	subject: "Hello",
	body: "<p>From your own domain</p>",
})

await mail({
	from: "hello@yourdomain.com",
	to: "someone@example.com",
	subject: "Hello",
	body: "<p>From your own domain</p>",
})

Team credentials

Your channel credentials — a Resend key, a Twilio SID, a Slack webhook — sync through your Postboi account, so a teammate (or your next machine) gets a working setup from one command:

bunx postboi sync   # pulls every synced credential your local env is missing

bunx postboi sync   # pulls every synced credential your local env is missing

postboi init pushes credentials up as it collects them and pulls them back down as it asks: a prompt whose value the team already synced answers itself. So for most projects this is invisible — one person runs init --sms and types TWILIO_AUTH_TOKEN once, ever; every teammate’s init or sync (already in the prepare script) fills it in from the team. Zero ceremony.

The rules, because these are secrets:

• Local values always win. sync only writes keys your environment is missing; a deliberate local override is never clobbered. postboi env pull --force is the explicit way to take the team’s values wholesale.
• POSTBOI_TOKEN never syncs. It’s per developer, and it’s the credential that unlocks the rest — the store must not contain its own key.
• Encrypted at rest, and only ever decrypted for a bearer of your account token: the same trust that could already send with those credentials.
• CLI-time only. Nothing in the send path reads this store — the library sends with whatever is in your process environment, servers included.

See what’s synced, push a hand-set var, or remove one:

bunx postboi env                # list (values masked)
bunx postboi env push           # push every known credential from your local env
bunx postboi env remove OLD_KEY

bunx postboi env                # list (values masked)
bunx postboi env push           # push every known credential from your local env
bunx postboi env remove OLD_KEY

Type-safe from

postboi init (and bunx postboi sync) generate types from your account’s sending address and domains, narrowing from so TypeScript rejects addresses you can’t send from, before the API does it at runtime:

await mail({ from: "foo@unknown-domain.com", ... })
// ^ Type error: must be your send.postboi.email address or an address
//   at one of your domains. Run `bunx postboi sync` to regenerate.

await mail({ from: "foo@unknown-domain.com", ... })
// ^ Type error: must be your send.postboi.email address or an address
//   at one of your domains. Run `bunx postboi sync` to regenerate.

Display-name form works too ("Joe Bloggs <hello@example.com>"), and pending domains are included deliberately: you can write the code while DNS propagates; deliverability is enforced at send time either way (from_not_allowed).

The generated types live inside the installed package (node_modules/postboi), so there’s no file in your project: nothing to commit, gitignore, or see in diffs. Three consequences of that:

• A reinstall resets them. init adds a "prepare": "postboi sync" script that restores them after every install (chained onto your existing prepare script, if any).
• They’re always optional. Without them (fresh clone, CI without a token, teammate who hasn’t run init), from falls back to plain string: builds and deploys never fail because the types are missing. sync itself is a quiet no-op without a POSTBOI_TOKEN and always exits 0, so it’s safe anywhere.
• They’re a snapshot. Re-run bunx postboi sync after adding or removing a domain (your editor may want a TS-server restart to pick the change up).

This only applies to the Postboi provider (we can’t know another provider’s identities). If you mix Postboi with a bring-your-own provider in one project, remove postboi sync from your prepare script: the narrowing applies to from everywhere.

Limits

The free tier stops at its caps; paid tiers keep sending and meter the overage. Every plan has a burst rate limit. When a limit is hit, mail() throws a PostboiError with a machine-readable code:

Delivery status

Every send appears in the message log with its delivery status: bounces and complaints are tracked automatically. High bounce or complaint rates pause sending to protect deliverability for everyone; the dashboard shows when that happens.

You can also look a message up from code with the id mail() returned:

const message = await mail.messages.get(id)
// { id, status: 'sent', to, subject, opened_at, open_count, … }

const message = await mail.messages.get(id)
// { id, status: 'sent', to, subject, opened_at, open_count, … }

And a scheduled message can be moved (until it sends). mail.messages.reschedule takes the same formats as scheduled_at:

await mail.messages.reschedule(id, { days: 2 }) // or a Date / ISO 8601 string

await mail.messages.reschedule(id, { days: 2 }) // or a Date / ISO 8601 string

Batching & idempotency

Personalized batches go out as one request to the batch endpoint (up to 100 recipients per call) instead of one per recipient:

await mail.send({
	to: ["ada@example.com", "linus@example.com"],
	subject: "Hey {name}",
	body: "<p>Hi {name}</p>",
	data: {
		"ada@example.com": { name: "Ada" },
		"linus@example.com": { name: "Linus" },
	},
})

await mail.send({
	to: ["ada@example.com", "linus@example.com"],
	subject: "Hey {name}",
	body: "<p>Hi {name}</p>",
	data: {
		"ada@example.com": { name: "Ada" },
		"linus@example.com": { name: "Linus" },
	},
})

Single sends accept an idempotency_key: retrying a send with the same key returns the original message id instead of delivering a duplicate. Pair it with retries for safe automatic retry.

Lists & broadcasts

The dashboard’s recipient lists are available from code, so a newsletter signup can go straight onto a list without leaving your app — one import, one call:

import { mail } from "postboi"

await mail.recipients.add("Newsletter", "Ada Lovelace <ada@example.com>")

import { mail } from "postboi"

await mail.recipients.add("Newsletter", "Ada Lovelace <ada@example.com>")

mail.recipients.add upserts on both sides. The first argument is a list name or id — an unknown name creates the list — and re-adding an address updates its name and data instead of duplicating it. Recipients take the same shapes as to: a bare address, "Name <a@b.c>", { email, name?, data? }, or an array mixing all three. (List names are unique per account, so mail.lists.create rejects a taken name with code name_taken.)

Every list method accepts a name or an id — only mail.recipients.add creates a missing list; everything else 404s on an unknown name. The response reports added (genuinely new addresses) and updated (existing ones refreshed), so calling it twice with the same address adds once:

await mail.recipients.add("Newsletter", [
	{ email: "ada@example.com", name: "Ada", data: { plan: "Pro" } },
	"Linus <linus@example.com>",
]) // → { added: 2, updated: 0, list: { id, name } }

await mail.lists.broadcast("Newsletter", {
	subject: "Hey {name}",
	body: "<p>News for our {plan} users…</p><p><a href='{unsubscribe_url}'>Unsubscribe</a></p>",
	scheduled_at: { hours: 1 }, // optional: omit to queue immediately
})

await mail.recipients.add("Newsletter", [
	{ email: "ada@example.com", name: "Ada", data: { plan: "Pro" } },
	"Linus <linus@example.com>",
]) // → { added: 2, updated: 0, list: { id, name } }

await mail.lists.broadcast("Newsletter", {
	subject: "Hey {name}",
	body: "<p>News for our {plan} users…</p><p><a href='{unsubscribe_url}'>Unsubscribe</a></p>",
	scheduled_at: { hours: 1 }, // optional: omit to queue immediately
})

{key} placeholders are filled per recipient from their data (plus {name} and {email} from the recipient row), and every broadcast automatically carries the one-click unsubscribe headers Gmail and Yahoo require for bulk mail. For a visible opt-out link in the body, drop in {unsubscribe_url} — a reserved variable filled with that recipient’s signed one-click link (the same target as the header). The rest of the surface: mail.lists.all(), mail.lists.get(id) (with recipients), mail.lists.rename(id, name), mail.lists.delete(id), and mail.recipients.remove(list_id, email).

Contacts (the audience)

A contact is one address on your account — its name and data live once and are shared across every list it’s on (not copied per list). Lists are how you segment that audience; a mail.recipients call upserts the contact and its membership together, so you rarely touch contacts directly. When you do, mail.contacts is the whole audience:

await mail.contacts.add("ada@example.com", { name: "Ada", data: { plan: "pro" } })
const ada = await mail.contacts.get("ada@example.com") // contact + its memberships
await mail.contacts.update("ada@example.com", { data: { plan: "team" } }) // global; last write wins
await mail.contacts.lists("ada@example.com") // which lists is Ada on?
await mail.contacts.all({ list: "Newsletter", status: "subscribed", search: "ada" }) // page (and follow) the audience
await mail.contacts.remove("ada@example.com") // drops the contact and all its memberships

await mail.contacts.add("ada@example.com", { name: "Ada", data: { plan: "pro" } })
const ada = await mail.contacts.get("ada@example.com") // contact + its memberships
await mail.contacts.update("ada@example.com", { data: { plan: "team" } }) // global; last write wins
await mail.contacts.lists("ada@example.com") // which lists is Ada on?
await mail.contacts.all({ list: "Newsletter", status: "subscribed", search: "ada" }) // page (and follow) the audience
await mail.contacts.remove("ada@example.com") // drops the contact and all its memberships

Because data is the contact’s, setting it through mail.recipients.add(list, { email, data }) writes the contact’s global data — the same values fill {key} in a broadcast from any list. Deleting a contact removes it from every list but does not suppress it; a hard bounce or complaint is suppressed separately (see Suppressions).

Confirmation (double opt-in)

Lists can require confirmation: new recipients start pending and receive an email with a personal confirm link; they only receive broadcasts (and count as new subscribers for notifications) once they click it. Manage it from the list’s Confirmation tab, or from code:

await mail.lists.update("Newsletter", { confirmation: true }) // or on create:
await mail.lists.create("Digest", { confirmation: true })

await mail.recipients.add("Newsletter", "ada@example.com")
// → { added: 1, updated: 0, pending: 1, list: … } — Ada gets the confirmation email

await mail.lists.update("Newsletter", { confirmation: true }) // or on create:
await mail.lists.create("Digest", { confirmation: true })

await mail.recipients.add("Newsletter", "ada@example.com")
// → { added: 1, updated: 0, pending: 1, list: … } — Ada gets the confirmation email

A membership carries a status — subscribed, pending or unsubscribed. Only subscribed members receive broadcasts and digests; an unsubscribe keeps the membership (with history) but out of every send. Hard bounces and complaints aren’t a per-list status — they suppress the address account-wide, and the send path drops suppressed addresses on its own (see Suppressions). Set a membership’s status explicitly too:

await mail.recipients.add("Newsletter", "ada@example.com", { status: "pending" })
await mail.recipients.set_status("Newsletter", "ada@example.com", "unsubscribed")

await mail.recipients.add("Newsletter", "ada@example.com", { status: "pending" })
await mail.recipients.set_status("Newsletter", "ada@example.com", "unsubscribed")

Two knobs, patchable via an object: enabled (send confirmation emails) and default_status (what new recipients start as). confirmation: true is shorthand for strict double opt-in (email + "pending"); a courtesy email without gating is { enabled: true, default_status: "subscribed" }; off again is confirmation: false. The object also takes subject, body (HTML with {key} variables plus {list} and {confirm_url} — put it in a link) and from. Settings come back on mail.lists.get(), and new members start "subscribed" or "pending" per the list’s default_status.

Notifications

Each list can carry notifications — digests of new subscribers emailed to whoever should know, on a schedule or the moment someone joins. The dashboard’s Notifications tab manages them visually; the same objects are available from code:

await mail.notifications.create("Newsletter", {
	recipients: "Darby <darby@uilo.co>",
	schedule: "subscribe", // fire when someone new joins
})

await mail.notifications.create("Newsletter", {
	recipients: ["darby@uilo.co", "team@uilo.co"],
	schedule: { frequency: "weekly", days: [1, 4], send_time: "09:00", timezone: "Europe/London" },
})

await mail.notifications.create("Newsletter", {
	recipients: "Darby <darby@uilo.co>",
	schedule: "subscribe", // fire when someone new joins
})

await mail.notifications.create("Newsletter", {
	recipients: ["darby@uilo.co", "team@uilo.co"],
	schedule: { frequency: "weekly", days: [1, 4], send_time: "09:00", timezone: "Europe/London" },
})

schedule takes a bare frequency ("daily", "weekly", "monthly", "subscribe") or an object with days (JS weekday numbers, weekly), month_day (monthly), send_time and an IANA timezone — defaults are Mondays, 09:00, UTC. Subject and body default to a starter template; bodies are HTML with {key} variables plus {#if}/{#each} blocks over new_subscribers. The rest of the surface: mail.notifications.all(list), mail.notifications.update(list, id, changes) (partial — absent fields keep their values), and mail.notifications.delete(list, id).

Suppressions

Hard bounces, complaints and unsubscribes land on your account’s suppression list, and sends to those addresses are dropped automatically. Inspect and manage it from code:

const rows = await mail.suppressions.all() // [{ email, reason, detail?, created_at }]
await mail.suppressions.add("noisy@example.com") // add by hand
await mail.suppressions.remove("fixed@example.com") // allow sending again

const rows = await mail.suppressions.all() // [{ email, reason, detail?, created_at }]
await mail.suppressions.add("noisy@example.com") // add by hand
await mail.suppressions.remove("fixed@example.com") // allow sending again

Notes

• scheduled_at schedules a send up to 30 days ahead. Scheduled messages appear in the dashboard’s Messages → Scheduled tab, where they can be rescheduled or canceled until they send. Scheduling counts against the free tier’s daily cap on the day it’s accepted; the monthly quota is charged when the message actually sends.
• scheduled_at accepts an ISO 8601 datetime string. Include an explicit timezone offset or Z (e.g. 2026-07-10T14:30:00Z or 2026-07-10T09:30:00-05:00). A bare local time without an offset is interpreted as UTC. It must be in the future and at most 30 days ahead.
• On Cloudflare Workers a POSTBOI_TOKEN binding is read automatically — see Cloudflare Workers. Pass new Postboi({ token }) only to override it.
• The token can be revoked and reissued any time from the dashboard’s API keys panel.