Documentación

Audiencias y Broadcasts

Importa contactos, dispara campañas masivas y respeta los requisitos de unsubscribe (RFC 8058).

1. Crea una audiencia

Una audiencia es una colección de contactos segmentada. Crea con POST /v1/product/audiences pasando name y descripción opcional.

create-audience.ts

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

2. Añade contactos

Usa POST /v1/product/audiences/:id/contacts para insertar contactos individualmente. Para importaciones masivas, haz llamadas en chunks respetando el 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. Crea un broadcast

Los broadcasts son campañas one-shot. Crea con POST /v1/product/broadcasts pasando audienceId, fromEmail, subject y templateId (o html propio).

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. Agenda o dispara

Usa scheduledAt para agendar. Si no, simplemente llama a POST /v1/product/broadcasts/:id/send para iniciar el envío inmediatamente.

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

Cabeceras RFC 8058

CoffeeMail inyecta automáticamente las cabeceras List-Unsubscribe y List-Unsubscribe-Post: List-Unsubscribe=One-Click en cada broadcast. No necesitas hacer nada.

Supresión automática

Las direcciones marcadas como spam (email.complained) o que hacen clic en el enlace de unsubscribe se añaden a la lista de supresión global de tu organización.