Postboi Cloud

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 Cloud when prompted. The CLI opens your browser to authorise the device, then writes two env vars:

• POSTBOI_TOKEN — your API key (keep it secret)
• POSTBOI_FROM — your sending address, e.g. darby@send.postboi.email

That’s the whole setup:

import { mail } from "postboi"

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

import { mail } from "postboi"

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

from is optional — when omitted (even without POSTBOI_FROM), the API uses your account’s sending address, which the token identifies.

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 — but it isn’t an inbox, so set reply_to if you want responses:

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.

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

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.

Notes

• scheduled_at isn’t supported on Cloud yet — sends are immediate.
• In runtimes without ambient env vars (e.g. Cloudflare Workers), pass the token explicitly: new Postboi({ token }).
• The token can be revoked and reissued any time from the dashboard’s API keys panel.