Providers

Each provider is its own entry point, so you only bundle the one you import. Every provider exposes the same send() and is_error() methods — swap providers without changing your calling code.

Want another provider? Quit being a baby and open a PR.

Using a provider directly

Useful when you want an explicit instance, or you’re on a runtime without ambient env vars (e.g. Cloudflare Workers):

import Resend from 'postboi/resend';

const mail = new Resend({
	api_key: process.env.RESEND_API_KEY!,
	default: { from: 'no-reply@example.com' }
});

await mail.send({
	to: 'someone@example.com',
	subject: 'hello',
	body: '<p>hello world</p>'
});

import Resend from 'postboi/resend';

const mail = new Resend({
	api_key: process.env.RESEND_API_KEY!,
	default: { from: 'no-reply@example.com' }
});

await mail.send({
	to: 'someone@example.com',
	subject: 'hello',
	body: '<p>hello world</p>'
});

Every provider also accepts default, timeout, retries, retry_delay, auto_text, and hooks on top of its own credentials — see Common constructor options.

Mock provider

postboi/mock records messages in-memory instead of sending them — same normalisation as a real provider. Perfect for tests.

import Mock from 'postboi/mock';

const mail = new Mock({ default: { from: 'no-reply@example.com' } });
await mail.send({ to: 'contact@example.com', subject: 'Hi', body: '<p>Hello</p>' });

expect(mail.sent).toHaveLength(1);

import Mock from 'postboi/mock';

const mail = new Mock({ default: { from: 'no-reply@example.com' } });
await mail.send({ to: 'contact@example.com', subject: 'Hi', body: '<p>Hello</p>' });

expect(mail.sent).toHaveLength(1);

Custom headers & tags

headers and tags on send() are forwarded to each provider’s native concept, and quietly ignored where unsupported:

• headers → Resend, Postmark, SendGrid, Mailgun (h:), Brevo, SparkPost, Mandrill, Plunk, Mailtrap, Scaleway, Cloudflare, SES, Mailjet, Elastic Email.
• tags → SendGrid (categories), Mailgun (o:tag), Brevo, MailerSend, Mandrill, MailPace, SES (EmailTags), Resend ({name,value} pairs). Postmark and Mailtrap use the first tag only.