API reference - Postboi

Provider class

Every provider exposes the same surface:

import Resend from 'postboi/resend';

const mail = new Resend({
	api_key: string, // see Providers for credential option names
	default?: { from?, to?, cc?, bcc?, reply_to? }
});

await mail.send(options: SendOptions): Promise<SendResponse>;
mail.is_error(error: unknown): error is PostboiError;

import Resend from 'postboi/resend';

const mail = new Resend({
	api_key: string, // see Providers for credential option names
	default?: { from?, to?, cc?, bcc?, reply_to? }
});

await mail.send(options: SendOptions): Promise<SendResponse>;
mail.is_error(error: unknown): error is PostboiError;

See Providers for each provider’s credential option names.

SendOptions

interface SendOptions {
	to?: Email | Email[];
	from?: Email;
	reply_to?: Email | Email[];
	cc?: Email | Email[];
	bcc?: Email | Email[];
	subject?: string; // default: "Mail sent from website"
	body: string | FormData;
	text?: string;
	formatter?:
		| {
				fieldset?: ((label: string) => string) | null | false;
				name?: ((label: string) => string) | null | false;
		  }
		| null
		| false;
	attachments?: File | File[];
	idempotency_key?: string;
	headers?: Record<string, string>;
	tags?: string[];
}

interface SendOptions {
	to?: Email | Email[];
	from?: Email;
	reply_to?: Email | Email[];
	cc?: Email | Email[];
	bcc?: Email | Email[];
	subject?: string; // default: "Mail sent from website"
	body: string | FormData;
	text?: string;
	formatter?:
		| {
				fieldset?: ((label: string) => string) | null | false;
				name?: ((label: string) => string) | null | false;
		  }
		| null
		| false;
	attachments?: File | File[];
	idempotency_key?: string;
	headers?: Record<string, string>;
	tags?: string[];
}

body accepts a string of HTML or a FormData object. formatter controls how grouped-field labels are rendered. headers and tags are forwarded to each provider’s native concept — see Custom headers & tags.

Common constructor options

Every provider also accepts these, on top of its own credentials:

{
	// field defaults applied when a send omits them; to/cc/bcc accept a string or array
	default?: { from?, to?, cc?, bcc?, reply_to? };
	timeout?: number; // per-request timeout in ms (default 30000)
	retries?: number; // retries on 429/5xx and network errors (default 0)
	retry_delay?: number; // base backoff in ms, doubles each attempt (default 500)
	auto_text?: boolean; // derive a plain-text body from the HTML (default false)
	hooks?: Hooks; // see Hooks
}

{
	// field defaults applied when a send omits them; to/cc/bcc accept a string or array
	default?: { from?, to?, cc?, bcc?, reply_to? };
	timeout?: number; // per-request timeout in ms (default 30000)
	retries?: number; // retries on 429/5xx and network errors (default 0)
	retry_delay?: number; // base backoff in ms, doubles each attempt (default 500)
	auto_text?: boolean; // derive a plain-text body from the HTML (default false)
	hooks?: Hooks; // see Hooks
}

See Errors & retries for retry behaviour and Hooks for the hooks shape.

Email type

type Email =
	| string // plain address or "Name <address>"
	| { address: string; name?: string };

type Email =
	| string // plain address or "Name <address>"
	| { address: string; name?: string };

All accepted address formats:

'user@example.com';
{ address: 'user@example.com', name: 'User Name' }
'User Name <user@example.com>';
['user1@example.com', 'user2@example.com'];

'user@example.com';
{ address: 'user@example.com', name: 'User Name' }
'User Name <user@example.com>';
['user1@example.com', 'user2@example.com'];

PostboiError

The normalised error thrown by every provider. See Errors & retries for usage.

interface PostboiError {
	provider: string; // e.g. "resend"
	status?: number; // HTTP status, when applicable
	code?: string; // provider-specific code, when available
	message: string; // normalised message
	raw: unknown; // the original provider payload
}

interface PostboiError {
	provider: string; // e.g. "resend"
	status?: number; // HTTP status, when applicable
	code?: string; // provider-specific code, when available
	message: string; // normalised message
	raw: unknown; // the original provider payload
}