Email for your app, set up with one command

---

Postboi is an email provider, and postboi is its TypeScript SDK. Run npx postboi init and mail() sends: no DNS, no card, no other provider to sign up for. Receiving, lists, webhooks and forms are already in the box.

3,000 emails a month are free, for good. After that it's £9 for 40,000 or £25 for 100,000, which is less than Resend charges for the same volume (Postboi or Resend?).

Already have a provider? mail() works with Resend, SES, Postmark and 40-odd others too, so switching is a line of config. You don't need any of them to use Postboi. And when you want more than email, the same API sends SMS, WhatsApp, push and chat.

📖 Docs · Pricing · Postboi compared · Dashboard

Quick start

bunx postboi init

Pick Postboi, sign in in the browser, and you're done. The CLI writes one secret:

# .env
POSTBOI_TOKEN=…

import { mail } from "postboi"

await mail({ to: "ada@example.com", subject: "Hi", body: "<p>Hello</p>" })

Mail goes out from you@send.postboi.email until you verify your own domain. Everything that isn't a secret (defaults, hooks, the captcha key) goes in a committed postboi.config.ts, and from is typed to the addresses your account can send from.

No one at the keyboard? bunx postboi init --agent sets up a project with no prompts and no sign-in. Sends stay sandboxed until someone claims it with one click. More on that.

What you get

• Sending, domains, lists and broadcasts, contacts, suppressions and a message log, all on the one token. The Postboi provider
• FormData to email. Hand mail() a FormData and it becomes a tidy HTML table, with attachments and grouped fields
• Hosted forms for sites with no backend, and spam protection (honeypot plus an invisible captcha)
• A dev inbox at /__postboi, so mail sent in development never reaches a real person
• Webhooks for delivered, opened, clicked and bounced, in one format whichever provider sent it
• Scheduling, tracking and one-click unsubscribe. Scheduling · Tracking
• Email testing. analyze() checks client support, Gmail clipping, alt text and links, offline, in any test suite
• Any HTML for the body, or Maizzle templates
• One error type, PostboiError, whichever provider failed

Bring your own provider

Pick Bring your own provider in postboi init instead. Your code stays the same:

// postboi.config.ts
import { config } from "postboi"

export default config({ provider: "resend", default: { from: "no-reply@example.com" } })

# .env
RESEND_API_KEY=re_xxxxxxxx

See all providers.

SvelteKit

A contact form action is one line:

// +page.server.ts
import { mail } from "postboi/kit"

export const actions = { default: mail }

Or use remote functions with postboi/remote and skip the server file. Postboi also has guides for Next.js, Astro, Nuxt, React Router, Hono, Express, Cloudflare Workers and Effect.

Beyond email

Run bunx postboi init --sms (or --whatsapp, --push, --chat) and call the function:

import { sms, whatsapp, push, slack, send } from "postboi"

await sms({ to: "+447788223344", message: "Your code is 4291" })
await whatsapp({ to: "+447788223344", template: "order_shipped", variables: { name: "Ada" } })
await push({ to: subscription, title: "Order shipped", message: "On its way" })
await slack({ message: "Deploy finished" })

// or try the cheapest channel first and stop when one works
await send({
	to: { push: subscription, sms: "+447788223344" },
	channels: "cheapest",
	message: "Your code is 4291",
})

In development, texts and WhatsApp messages are logged, not sent. SMS · WhatsApp · Push · Chat · send()

For AI agents

• bunx postboi skill installs a skill that teaches the whole library, at .claude/skills/postboi/ and .agents/skills/postboi/. It also ships in the package at node_modules/postboi/skills/postboi/SKILL.md.
• The docs pages render client-side, so fetch plain Markdown from https://docs.postboi.app/raw/<slug>, or everything at once from /llms-full.txt.

Development

The repo builds and tests with Bun and Node 22.22.3+, 24.15+ or 26+, the versions its whole toolchain installs on. devEngines in package.json holds that range, and npm 10.9 or later refuses to run here on any other Node. Bun doesn't read it, so bun run goes ahead on whatever Node is on your PATH.

bun install
bun run dev     # the docs site
bun run check   # types
bun run lint
bun run test
bun run build   # the package

Deploying the docs site

The docs are a SvelteKit site on Cloudflare Workers, described in alchemy.run.ts as an alchemy stack: Cloudflare.Website.SvelteKit builds the site and deploys it with no adapter. The Worker's settings (name, compatibility date and flags, observability, workers.dev and preview URLs) come from wrangler.jsonc, which the stack reads, so the two ways of deploying can't disagree.

bun run infra:plan -- --stage prod       # what a deploy would change
bun run infra:deploy -- --stage prod     # docs.postboi.app, from main
bun run infra:deploy -- --stage pr-123   # a pull request's preview, on its workers.dev URL
bun run infra:destroy -- --stage pr-123  # and take it down again

It needs CLOUDFLARE_API_TOKEN and CLOUDFLARE_ACCOUNT_ID in the environment (or alchemy profile). Production deploys itself: .github/workflows/deploy-docs.yml runs the --stage prod deploy from main after CI passes on a push and after every release.

PRs are welcome, new providers especially. Match the code style (snake_case, no semicolons), add tests, and run check and lint before pushing. Releases are covered in RELEASING.md.