Tracking & unsubscribe

Open & click tracking

Turn tracking on or off per send with tracking (no dashboard digging, and the same option whatever the provider):

import { mail } from 'postboi'

await mail({
	to: 'contact@example.com',
	subject: 'Your receipt',
	body: '<p>Thanks for your order.</p>',
	tracking: { opens: true, clicks: false }
})

import { mail } from 'postboi'

await mail({
	to: 'contact@example.com',
	subject: 'Your receipt',
	body: '<p>Thanks for your order.</p>',
	tracking: { opens: true, clicks: false }
})

Only the flags you set are forwarded, so the provider’s own defaults keep applying to anything you leave out. The resulting open/click events arrive via webhooks, including which client and device opened the mail.

Provider support

Providers whose tracking is configured at the domain level (Resend) or account level ignore the per-send flags. Configure tracking in their dashboard instead. Every other provider without a tracking concept ignores the flags entirely, matching how scheduled_at behaves.

One-click unsubscribe

Bulk senders to Gmail and Yahoo are required to support RFC 8058 one-click unsubscribe. One option sets both headers on any headers-capable provider:

await mail({
	to: 'subscriber@example.com',
	subject: 'March newsletter',
	body: newsletter_html,
	unsubscribe_url: 'https://example.com/unsubscribe?u=123&list=news'
})

await mail({
	to: 'subscriber@example.com',
	subject: 'March newsletter',
	body: newsletter_html,
	unsubscribe_url: 'https://example.com/unsubscribe?u=123&list=news'
})

That adds:

List-Unsubscribe: <https://example.com/unsubscribe?u=123&list=news>
List-Unsubscribe-Post: List-Unsubscribe=One-Click

List-Unsubscribe: <https://example.com/unsubscribe?u=123&list=news>
List-Unsubscribe-Post: List-Unsubscribe=One-Click

Your endpoint must accept the one-click POST (no confirmation page: mail clients POST it directly). If you set your own List-Unsubscribe header explicitly in headers, it wins over the generated one.

Plain-text bodies are automatic

Every HTML send also ships a derived plain-text alternative by default (auto_text): better spam scores, and text-only clients get something readable. Provide text yourself to control it, or opt out globally:

// postboi.config.ts
export default config({ auto_text: false })

// postboi.config.ts
export default config({ auto_text: false })