Documentation

Audiences and Broadcasts

Import contacts, dispatch mass campaigns and respect RFC 8058 unsubscribe requirements.

1. Create an audience

An audience is a segmented contact collection. Create with POST /v1/product/audiences passing name and optional description.

create-audience.ts

const { data } = await coffeemail.audiences.create({  name: 'Newsletter PT',  description: 'Leads do blog BR',});

2. Add contacts

Use POST /v1/product/audiences/:id/contacts to insert contacts individually. For bulk imports, make calls in chunks respecting the rate limit.

bulk-import.ts

const contacts = [  { email: 'maria@example.com', firstName: 'Maria' },  { email: 'joao@example.com', firstName: 'João', metadata: { plan: 'pro' } },]; for (const contact of contacts) {  await coffeemail.audiences.contacts.create('aud_123', contact);}

3. Create a broadcast

Broadcasts are one-shot campaigns. Create with POST /v1/product/broadcasts passing audienceId, fromEmail, subject and templateId (or own html).

create-broadcast.ts

const { data } = await coffeemail.broadcasts.create({  audienceId: 'aud_123',  fromEmail: 'news@seudominio.com.br',  subject: 'Novidades da semana',  templateId: 'tpl_welcome',  variables: { name: 'assinante' },});

4. Schedule or fire

Use scheduledAt to schedule. Otherwise, just call POST /v1/product/broadcasts/:id/send to start sending immediately.

send-broadcast.ts

await coffeemail.broadcasts.create({  audienceId: 'aud_123',  fromEmail: 'news@seudominio.com.br',  subject: 'Black Friday 2026',  templateId: 'tpl_bf',  scheduledAt: new Date('2026-11-25T12:00:00.000Z'),}); await coffeemail.broadcasts.send('bc_123');

RFC 8058 headers

CoffeeMail automatically injects the List-Unsubscribe and List-Unsubscribe-Post: List-Unsubscribe=One-Click headers on every broadcast. You don't need to do anything.

Automatic suppression

Addresses marked as spam (email.complained) or that click the unsubscribe link are added to your organization's global suppression list.