Global config

Set your provider, defaults, and behaviour once and have them apply to every send. A postboi.config.ts at your project root is the committed home for everything except secrets — bunx postboi init writes it for you. It’s also the only place hooks can live, since they’re functions.

// postboi.config.ts
import { config } from 'postboi';

export default config({
	provider: 'resend',
	default: { from: 'no-reply@example.com' },
	options: { domain: 'mg.example.com' }, // non-secret provider options
	retries: 2,
	hooks: {
		on: {
			error: ({ error }) => Sentry.captureException(error)
		}
	}
});

// postboi.config.ts
import { config } from 'postboi';

export default config({
	provider: 'resend',
	default: { from: 'no-reply@example.com' },
	options: { domain: 'mg.example.com' }, // non-secret provider options
	retries: 2,
	hooks: {
		on: {
			error: ({ error }) => Sentry.captureException(error)
		}
	}
});

It auto-loads on the first mail() (Node/Bun).

Keep secrets out of this file — API keys and tokens belong in the environment. To vary the provider per environment, see Per-environment config.

Precedence

Lowest to highest — later sources win:

1. postboi.config.ts
2. environment variables — POSTBOI_PROVIDER, POSTBOI_* defaults, and each provider’s own field vars (e.g. MAILGUN_DOMAIN)
3. options passed explicitly to mail() or a provider constructor

Edge runtimes

Edge runtimes (Cloudflare Workers, etc.) have no filesystem, so the config file can’t be auto-loaded. Register config at startup instead with configure({ ... }).

import { configure } from 'postboi';

configure({
	default: { from: 'no-reply@example.com' },
	retries: 2
});

import { configure } from 'postboi';

configure({
	default: { from: 'no-reply@example.com' },
	retries: 2
});