Introduction

Postboi is an email provider, and postboi is its TypeScript SDK. We run the sending infrastructure, like Resend, Postmark or SendGrid do. Run postboi init, get a POSTBOI_TOKEN, and mail() sends. You don’t need an account anywhere else, a DNS record or a card. The Postboi provider comes with custom domains, lists and broadcasts, contacts, suppressions, a message log, webhooks, hosted forms and receiving.

If you’d rather use a provider you already have, you can. The same call works with Resend, SES, Postmark and 40-odd others, and switching is a line of config. You don’t need any of them to use Postboi, though. Comparing Postboi with another email service? See Postboi compared.

What’s in Postboi

Transactional email is the core of it: sign-in links, codes, receipts and resets, with delivery status, idempotency keys, retries, suppressions and webhooks. Around that:

Building with an AI agent? Email for agents puts the pieces an agent needs on one page.

Import a channel and call it. On the email side, hand mail() a FormData and it turns it into a tidy HTML table.

import { mail, sms } from 'postboi'

await mail({ to: 'contact@example.com', subject: 'Hi', body: '<p>Hello</p>' })
await sms({ to: '+44 7788 223344', message: 'Your code is 4291' })

Features

• ☁️ Postboi is the provider: send email with one token and no other account.
• 👨‍💻 Zero configuration: works out of the box with minimal setup.
• 🔌 Or use your own provider: swap providers on any channel without changing your code.
• 💬 Five channels, one shape: sms(), whatsapp(), push(), slack() and friends resolve, hook and error exactly like mail().
• 📡 Multi-channel send(): fan out to every channel, or stop at the cheapest one that works.
• 📝 Smart FormData parsing: automatically converts FormData to HTML tables.
• 🎯 Grouped fields: organise form fields with fieldset→field syntax.
• 📎 Attachments: attach files directly from form inputs or File objects.
• 📮 Hosted forms: no backend? Point any HTML <form> at a hosted endpoint and submissions land in your inbox, spam-checked.
• 🎨 Bring your own templates: body takes any HTML (or a promise of it), and the optional postboi/maizzle helper renders Maizzle templates straight into it.
• 🛡️ Type-safe: full TypeScript support with normalised error handling.

How it fits together

There are three ways to use Postboi, from least to most explicit:

1. Zero-config channel calls: mail(), sms(), whatsapp(), push(), slack() and friends: each reads its provider and defaults from a committed postboi.config.ts, and secrets from the environment. Best for apps where one provider per channel is set per environment.
2. postboi/kit form actions: a one-line SvelteKit action that reads FormData, sends it, and returns a result.
3. A provider instance: new Resend({ ... }) or new Twilio({ ... }) when you want an explicit instance, or credentials that don’t come from the environment.

Start with the Quick start and let the CLI wire everything up for you, or set things up by hand with Manual setup.

Next steps