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.

Zero setup for agents & CI

postboi init --agent removes the last human step. No browser, no sign-in, no prompts — one API round trip mints a claimable project and the CLI wires everything exactly as the interactive flow would:

bunx postboi init --agent

bunx postboi init --agent

• The token lands in .env (gitignored automatically), the config is written, the package installed, the agent skill linked.
• Your sending address is your project’s name. The package.json name seeds the slug: @acme/mail-site sends from mail-site@send.postboi.email (a suffix is added if it’s taken, and a friendly random slug stands in when the name can’t be an address).
• Sends work immediately, sandboxed. Every send runs the full pipeline — message log, webhooks, status — but nothing is delivered and nothing can reach a real inbox. The response says so: { id, sandbox: true, claim_url }.
• One sign-in makes it real. The CLI prints a claim URL; opening it and signing in (a magic link — that’s the account creation too) transfers the project to you and lifts the sandbox. Everything the agent built keeps working unchanged, and the sandboxed sends are waiting in your message log.
• Unclaimed projects expire. A project nobody claims and nobody uses for 14 days is deleted. Activity counts — while your token keeps sending sandboxed mail, the project stays alive for you to claim — but 60 days unclaimed is the ceiling, active or not.

In development none of this even matters yet — with the dev inbox running, mail is captured locally before the provider is consulted, so the sandbox only shows up in deployed or production-mode sends.

If you’re an AI coding agent: run init --agent when no POSTBOI_TOKEN exists and no human is available to sign in, then surface the claim URL prominently in your summary — it’s the one thing only your human can do. postboi whoami re-prints it any time. The other channels accept the flag too (init --push --agent mints VAPID keys and wires the service worker with no prompts); channels that need paid credentials (SMS, WhatsApp) will tell you exactly which env var they’re missing instead of prompting.

--agent also detects the project’s domain (astro site, package.json homepage, a CNAME file, wrangler routes, SITE_URL-style env vars) and prints it as a suggestion rather than registering it — ownership is the human’s to assert, and the API refuses domains on unclaimed projects outright, so an anonymous token can never squat one. After the claim, bunx postboi domains add <domain> prints the records and the one-click registrar link.

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.

Receiving on your own domain

Your domain receives as well as sends, on a dedicated subdomain — and for a new domain it’s part of standard setup: the two records it needs (a TXT and an MX, both on reply.yourdomain.com) are in the same list as the sending ones, covered by the same one-click registrar apply where yours supports it. Once they’re live, mail to any address on that subdomain — support@reply.yourdomain.com, ada+ticket-42@reply.yourdomain.com — lands in Received, fires email.received, and can be answered from the dashboard, where the reply goes out from the address the mail was written to. The switch on the domain turns receiving off (and back on for domains added before this was the default, or via POST /v1/domains/{id}/inbound).

The MX lives on the subdomain on purpose. Pointing your domain’s own MX at us would take over your real mailboxes, so that is never asked for — you@yourdomain.com keeps working exactly as before, wherever it’s hosted.

Sending from your own domain

init offers this at the end of setup — it detects your project’s domain (astro site, package.json homepage, a CNAME file, wrangler routes, SITE_URL-style env vars) and prefills the prompt, so accepting is one Enter. Or do it any time from the terminal (bunx postboi domains add yourdomain.com — prints the records and a one-click registrar link) or the dashboard: add a domain, publish the three DKIM CNAME records it shows you, and hit Check. Every plan includes one custom domain — Free included — and paid plans are uncapped (domain_limit_exceeded past the cap). 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.
• Used server-side for exactly three things. The library itself sends with whatever is in your process environment, servers included — the synced store never feeds your send path. On Postboi’s side, synced credentials are decrypted only to poll a provider that can’t push delivery webhooks (SMTP, Microsoft 365, Cloudflare — on by default once synced, pausable per provider on the credentials page); to send on your behalf when you’ve turned on send via there; and, for a provider whose delivery events you point at us, to verify those webhooks with its signing secret — plus to register the webhook with that provider when you press Register, which stores any key it hands back. Never otherwise.

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

Relay: send via your own provider

With credentials synced, the credentials page grows a Send via setting: pick a provider and the account’s sends go out through it — Postboi keeps the message log, the suppression list, webhooks and the dashboard timeline, while your Resend, Postmark, Cloudflare (or any other synced provider) does the delivering. Your code doesn’t change: you keep sending through the Postboi provider exactly as before.

// Or per send, without touching the account setting:
const mail = new Postboi({ send_via: "resend" })

// Or per send, without touching the account setting:
const mail = new Postboi({ send_via: "resend" })

What flows back depends on the target:

• SMTP, Microsoft 365, Cloudflare — the providers without webhooks — get their delivery and bounce events polled (see webhooks) and correlated into the timeline, so a relayed send shows Delivered/Bounced like a native one.
• Webhook-capable providers (Resend, Postmark, …) report events to whatever webhooks you configure with them; the Postboi timeline shows Sent only. Cloudflare’s send response reports per-recipient verdicts immediately, bounces included.

Two honest notes: set from to an address the relay provider can send as (the usual from rule is skipped for relayed sends — your provider enforces its own sender authentication, and anything it can’t authenticate fails with its error), and relayed sends still count toward your Postboi plan like any other send.

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" },
	},
})

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.

A batch takes one key and gives each recipient its own, suffixed with that recipient’s position — order-42 becomes order-42:0, order-42:1 and so on. One key names one message, so a batch whose items shared a key would be a batch claiming to be a single message; the suffix is what keeps a retry replaying item by item, returning the ids the first attempt got and sending only what never went. The position is the one in your original to array, so a before.send hook skipping a different recipient the second time round doesn’t shift the keys onto other people’s messages.

Keys are capped at 256 characters including the suffix — a base key too long to carry one is refused before anything is sent, rather than silently truncated into a key that could collide with another.

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.update("ada@example.com", { phone: "+447788223344" }) // the number SMS and WhatsApp reach
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.update("ada@example.com", { phone: "+447788223344" }) // the number SMS and WhatsApp reach
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

A contact’s phone is its delivery profile beyond email: one mobile number in E.164 (+447788223344 — a national number is rejected rather than guessed at), the one an sms() or whatsapp() to that person goes to. Email stays the handle; the number is a fact about the contact, searchable alongside the name.

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).

New in 0.19 (breaking). Recipients became contacts: name/data are now the contact’s, shared across its lists (last write wins) rather than stored per list; the per-list status enum is subscribed | pending | unsubscribed (bounced/complained are suppressions, not a status); and mail.contacts.* is a new namespace. mail.recipients.* keeps the same signatures — it’s contact-backed now.

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() // [{ channel, email | phone, 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() // [{ channel, email | phone, reason, detail?, created_at }]
await mail.suppressions.add("noisy@example.com") // add by hand
await mail.suppressions.remove("fixed@example.com") // allow sending again

The list is per channel. An email address is one entry; a phone number is suppressed for SMS and for WhatsApp separately, because “stop texting me” and “stop messaging me on WhatsApp” are two different things a person can say. A bare string is an email; a number goes in as { phone }, SMS unless told otherwise:

await mail.suppressions.add({ phone: "+447788223344" }) // SMS
await mail.suppressions.add({ phone: "+447788223344", channel: "whatsapp" })
await mail.suppressions.all({ channel: "sms" }) // just the numbers, just that channel

await mail.suppressions.add({ phone: "+447788223344" }) // SMS
await mail.suppressions.add({ phone: "+447788223344", channel: "whatsapp" })
await mail.suppressions.all({ channel: "sms" }) // just the numbers, just that channel

Each row says which it is — narrow on channel before reading the address, because an email row carries email and a text row carries phone, never a number in a field called email:

for (const row of await mail.suppressions.all()) {
	if (row.channel === "email") console.log(row.email, row.reason)
	else console.log(row.channel, row.phone, row.reason)
}

for (const row of await mail.suppressions.all()) {
	if (row.channel === "email") console.log(row.email, row.reason)
	else console.log(row.channel, row.phone, row.reason)
}

A texted STOP reaches the list on its own when Twilio delivery receipts are polled for the account — see opt-outs on the SMS page — and the same { phone } shape adds one by hand from wherever else a reply arrives.

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.