Documentação

Audiências e Broadcasts

Importe contatos, dispare campanhas em massa e respeite os requisitos de unsubscribe (RFC 8058).

1. Crie uma audiência

Uma audiência é uma coleção de contatos segmentada. Crie com POST /v1/product/audiences passando name e description opcional.

create-audience.ts

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

2. Adicione contatos

Use POST /v1/product/audiences/:id/contacts para inserir contatos individualmente. Para importações em massa, faça chamadas em chunks respeitando o 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. Crie um broadcast

Broadcasts são campanhas one-shot. Crie com POST /v1/product/broadcasts passando audienceId, fromEmail, subject e templateId (ou html próprio).

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. Agende ou dispare

Use scheduledAt para agendar. Caso contrário, basta chamar POST /v1/product/broadcasts/:id/send para iniciar o envio imediatamente.

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');

Headers RFC 8058

A CoffeeMail injeta automaticamente os cabeçalhos List-Unsubscribe e List-Unsubscribe-Post: List-Unsubscribe=One-Click em todo broadcast. Você não precisa fazer nada.

Supressão automática

Endereços marcados como spam (email.complained) ou que clicam no link de unsubscribe são adicionados à lista de supressão global da sua organização.