Documentation

SDK Node

v0.1.0

Referencia completa del paquete @coffeemail/node. Cobertura total de la API de Producto con retorno seguro en el patrón data, error y errores tipados.

Instalación

.bash

npm i @coffeemail/node@0.1.0

Cliente

Crea una instancia del cliente. La clave puede venir del constructor o de la variable de entorno COFFEEMAIL_API_KEY.

new CoffeeMail(apiKey?: string, options?: CoffeeMailClientOptions): CoffeeMail

coffeemail.ts

import { CoffeeMail } from '@coffeemail/node'; const coffeemail = new CoffeeMail(process.env.COFFEEMAIL_API_KEY, {  locale: 'es',  timeoutMs: 10_000,});

coffeemail.Emails

SDK Node

.send

coffeemail.emails.send(payload): Promise<CoffeeMailResponse<SendEmailResponse>>

Pone en cola un email transaccional.

send-basic.ts

const { data, error } = await coffeemail.emails.send({  from: 'noreply@seudominio.com.br',  to: 'cliente@example.com',  subject: 'Confirmação do pedido #123',  html: '<h1>Obrigado!</h1><p>Seu pedido está em processamento.</p>',  text: 'Obrigado! Seu pedido está em processamento.',}); if (error) throw error;console.log('Email enfileirado:', data.id);

SDK Node

.sendBatch

coffeemail.emails.sendBatch(items): Promise<CoffeeMailResponse<SendBatchResponse>>

Envia hasta 100 emails en una sola llamada.

sendBatch.ts

const { data, error } = await coffeemail.emails.sendBatch([  { from: 'noreply@seudominio.com.br', to: 'a@x.com', subject: 'A', html: '<p>A</p>' },  { from: 'noreply@seudominio.com.br', to: 'b@x.com', subject: 'B', html: '<p>B</p>' },]);

SDK Node

.get

coffeemail.emails.get(id): Promise<CoffeeMailResponse<EmailDetail>>

Detalla un email por ID.

get.ts

const { data } = await coffeemail.emails.get('eml_8f3a2c1b');console.log('Status atual:', data.status);

SDK Node

.list

coffeemail.emails.list(query?): Promise<CoffeeMailResponse<ListEmailsResponse>>

Lista emails enviados con filtros y paginacion.

list.ts

const { data } = await coffeemail.emails.list({ status: 'delivered', limit: 20 });

SDK Node

.getEvents

coffeemail.emails.getEvents(id): Promise<CoffeeMailResponse<EmailEventsResponse>>

Devuelve la linea de tiempo de eventos del email.

getEvents.ts

const { data } = await coffeemail.emails.getEvents('eml_8f3a2c1b');

SDK Node

.cancel

coffeemail.emails.cancel(id): Promise<CoffeeMailResponse<void>>

Cancela un email programado antes del envio.

cancel.ts

await coffeemail.emails.cancel('eml_agendado_123');

SDK Node

.resend

coffeemail.emails.resend(id): Promise<CoffeeMailResponse<SendEmailResponse>>

Reenvia un email existente.

resend.ts

const { data } = await coffeemail.emails.resend('eml_8f3a2c1b');

coffeemail.Dominios

SDK Node

.create

coffeemail.domains.create(payload): Promise<CoffeeMailResponse<DomainDetail>>

Agrega un dominio y devuelve los registros DNS.

create.ts

const { data } = await coffeemail.domains.create({ name: 'transacional.seudominio.com.br' });

SDK Node

.list

coffeemail.domains.list(query?): Promise<CoffeeMailResponse<ListDomainsResponse>>

Lista los dominios de la organizacion.

list.ts

const { data } = await coffeemail.domains.list();

SDK Node

.get

coffeemail.domains.get(id): Promise<CoffeeMailResponse<DomainDetail>>

Detalla un dominio.

get.ts

const { data } = await coffeemail.domains.get('dom_123');

SDK Node

.verify

coffeemail.domains.verify(id): Promise<CoffeeMailResponse<DomainVerificationResult>>

Ejecuta la verificacion DNS activa.

verify.ts

const { data } = await coffeemail.domains.verify('dom_123');

SDK Node

.getHealth

coffeemail.domains.getHealth(id): Promise<CoffeeMailResponse<DomainHealthResponse>>

Diagnostico de reputacion y listas negras.

getHealth.ts

const { data } = await coffeemail.domains.getHealth('dom_123');

SDK Node

.delete

coffeemail.domains.delete(id): Promise<CoffeeMailResponse<void>>

Elimina el dominio de la organizacion.

delete.ts

await coffeemail.domains.delete('dom_123');

coffeemail.Plantillas

SDK Node

.create

coffeemail.templates.create(payload): Promise<CoffeeMailResponse<TemplateDetail>>

Registra una plantilla (handlebars o react_email).

create.ts

const { data } = await coffeemail.templates.create({  name: 'Boas-vindas',  subject: 'Bem-vindo, {{ name }}!',  html: '<h1>Oi {{ name }}</h1>',  format: 'handlebars',});

SDK Node

.list

coffeemail.templates.list(query?): Promise<CoffeeMailResponse<ListTemplatesResponse>>

Lista plantillas de la organizacion.

list.ts

const { data } = await coffeemail.templates.list();

SDK Node

.get

coffeemail.templates.get(id): Promise<CoffeeMailResponse<TemplateDetail>>

Detalla una plantilla.

get.ts

const { data } = await coffeemail.templates.get('tpl_123');

SDK Node

.update

coffeemail.templates.update(id, patch): Promise<CoffeeMailResponse<TemplateDetail>>

Actualiza una plantilla existente.

update.ts

await coffeemail.templates.update('tpl_123', { subject: 'Novo assunto' });

SDK Node

.delete

coffeemail.templates.delete(id): Promise<CoffeeMailResponse<void>>

Elimina una plantilla.

delete.ts

await coffeemail.templates.delete('tpl_123');

SDK Node

.format

coffeemail.templates.format(payload): Promise<CoffeeMailResponse<FormatTemplateResponse>>

Formatea e indenta el código HTML/Handlebars de la plantilla.

format.ts

const { data } = await coffeemail.templates.format({ html: '<h1>Olá</h1>' });

SDK Node

.testRender

coffeemail.templates.testRender(payload): Promise<CoffeeMailResponse<RenderPreviewResponse>>

Renderiza la plantilla con sanitización de etiquetas e inyección de variables.

testRender.ts

const { data } = await coffeemail.templates.testRender({ html: '<h1>Oi {{ name }}</h1>', variables: { name: 'João' } });

SDK Node

.listStarters

coffeemail.templates.listStarters(): Promise<CoffeeMailResponse<ListStartersResponse>>

Lista las plantillas base preconstruidas de la plataforma.

listStarters.ts

const { data } = await coffeemail.templates.listStarters();

SDK Node

.getStarter

coffeemail.templates.getStarter(id): Promise<CoffeeMailResponse<StarterTemplateDetail>>

Detalla una plantilla base por identificador o slug.

getStarter.ts

const { data } = await coffeemail.templates.getStarter('starter_auth_otp');

coffeemail.Audiencias

SDK Node

.create

coffeemail.audiences.create(payload): Promise<CoffeeMailResponse<AudienceDetail>>

Crea una audiencia.

create.ts

const { data } = await coffeemail.audiences.create({ name: 'Clientes Ativos' });

SDK Node

.list

coffeemail.audiences.list(): Promise<CoffeeMailResponse<ListAudiencesResponse>>

Lista audiencias.

list.ts

const { data } = await coffeemail.audiences.list();

SDK Node

.get

coffeemail.audiences.get(id): Promise<CoffeeMailResponse<AudienceDetail>>

Detalla una audiencia.

get.ts

const { data } = await coffeemail.audiences.get('aud_123');

SDK Node

.update

coffeemail.audiences.update(id, patch): Promise<CoffeeMailResponse<AudienceDetail>>

Actualiza el nombre o descripción de una audiencia.

update.ts

await coffeemail.audiences.update('aud_123', { name: 'Novo Nome' });

SDK Node

.delete

coffeemail.audiences.delete(id): Promise<CoffeeMailResponse<void>>

Elimina una audiencia.

delete.ts

await coffeemail.audiences.delete('aud_123');

SDK Node

.contacts.create

coffeemail.audiences.contacts.create(audienceId, payload): Promise<CoffeeMailResponse<ContactDetail>>

Agrega un contacto a la audiencia.

contacts.create.ts

await coffeemail.audiences.contacts.create('aud_123', {  email: 'maria@example.com',  firstName: 'Maria',  metadata: { plan: 'pro' },});

SDK Node

.contacts.bulkAdd

coffeemail.audiences.contacts.bulkAdd(audienceId, contacts): Promise<CoffeeMailResponse<BulkAddResult>>

Importa múltiples contactos en lote para una audiencia.

contacts.bulkAdd.ts

await coffeemail.audiences.contacts.bulkAdd('aud_123', [  { email: 'user1@example.com', firstName: 'User 1' },  { email: 'user2@example.com', firstName: 'User 2' },]);

SDK Node

.contacts.list

coffeemail.audiences.contacts.list(audienceId, query?): Promise<CoffeeMailResponse<ListContactsResponse>>

Lista contactos de una audiencia.

contacts.list.ts

const { data } = await coffeemail.audiences.contacts.list('aud_123', { limit: 100 });

SDK Node

.contacts.update

coffeemail.audiences.contacts.update(audienceId, contactId, payload): Promise<CoffeeMailResponse<ContactDetail>>

Actualiza los atributos o metadatos de un contacto.

contacts.update.ts

await coffeemail.audiences.contacts.update('aud_123', 'ctc_456', { firstName: 'Novo Nome' });

SDK Node

.contacts.delete

coffeemail.audiences.contacts.delete(audienceId, contactId): Promise<CoffeeMailResponse<void>>

Elimina un contacto de la audiencia.

contacts.delete.ts

await coffeemail.audiences.contacts.delete('aud_123', 'ctc_456');

coffeemail.Broadcasts

SDK Node

.create

coffeemail.broadcasts.create(payload): Promise<CoffeeMailResponse<BroadcastDetail>>

Crea una campana para una audiencia.

create.ts

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

SDK Node

.list

coffeemail.broadcasts.list(query?): Promise<CoffeeMailResponse<ListBroadcastsResponse>>

Lista campanas.

list.ts

const { data } = await coffeemail.broadcasts.list({ limit: 50 });

SDK Node

.get

coffeemail.broadcasts.get(id): Promise<CoffeeMailResponse<BroadcastDetail>>

Detalla una campana.

get.ts

const { data } = await coffeemail.broadcasts.get('bc_123');

SDK Node

.send

coffeemail.broadcasts.send(id): Promise<CoffeeMailResponse<BroadcastDetail>>

Envia la campana. Los encabezados RFC 8058 se inyectan automaticamente.

send.ts

await coffeemail.broadcasts.send('bc_123');

SDK Node

.cancel

coffeemail.broadcasts.cancel(id): Promise<CoffeeMailResponse<void>>

Cancela una campana que aun no se ha enviado.

cancel.ts

await coffeemail.broadcasts.cancel('bc_123');

coffeemail.Supresiones

SDK Node

.list

coffeemail.suppressions.list(query?): Promise<CoffeeMailResponse<ListSuppressionsResponse>>

Lista entradas de la lista de supresion.

list.ts

const { data } = await coffeemail.suppressions.list({ limit: 100 });

SDK Node

.create

coffeemail.suppressions.create(payload): Promise<CoffeeMailResponse<SuppressionDetail>>

Agrega manualmente una entrada.

create.ts

await coffeemail.suppressions.create({  email: 'optout@example.com',  reason: 'unsubscribe',  category: 'global',});

SDK Node

.get

coffeemail.suppressions.get(id): Promise<CoffeeMailResponse<SuppressionDetail>>

Consulta los detalles y motivo de una supresión específica.

get.ts

const { data } = await coffeemail.suppressions.get('sup_123');

SDK Node

.delete

coffeemail.suppressions.delete(id): Promise<CoffeeMailResponse<void>>

Elimina una entrada.

delete.ts

await coffeemail.suppressions.delete('sup_123');

SDK Node

.reactivate

coffeemail.suppressions.reactivate(id): Promise<CoffeeMailResponse<void>>

Reactiva un destinatario suprimido para volver a recibir envíos.

reactivate.ts

await coffeemail.suppressions.reactivate('sup_123');

coffeemail.Webhooks

SDK Node

.create

coffeemail.webhooks.create(payload): Promise<CoffeeMailResponse<WebhookDetail>>

Registra un endpoint HTTPS.

create.ts

const { data } = await coffeemail.webhooks.create({  url: 'https://api.seusite.com.br/webhooks/coffeemail',  events: ['email.delivered', 'email.bounced', 'email.complained'],  secret: process.env.WEBHOOK_SECRET,});

SDK Node

.list

coffeemail.webhooks.list(): Promise<CoffeeMailResponse<ListWebhooksResponse>>

Lista webhooks registrados.

list.ts

const { data } = await coffeemail.webhooks.list();

SDK Node

.get

coffeemail.webhooks.get(id): Promise<CoffeeMailResponse<WebhookDetail>>

Detalla un webhook.

get.ts

const { data } = await coffeemail.webhooks.get('wh_123');

SDK Node

.update

coffeemail.webhooks.update(id, patch): Promise<CoffeeMailResponse<WebhookDetail>>

Actualiza URL, eventos o secret.

update.ts

await coffeemail.webhooks.update('wh_123', {  events: ['email.delivered', 'email.bounced', 'email.complained', 'email.opened'],});

SDK Node

.toggle

coffeemail.webhooks.toggle(id, status: 'active' | 'paused'): Promise<CoffeeMailResponse<WebhookDetail>>

Activa o pausa la entrega de eventos en el webhook.

toggle.ts

await coffeemail.webhooks.toggle('wh_123', 'paused');

SDK Node

.delete

coffeemail.webhooks.delete(id): Promise<CoffeeMailResponse<void>>

Elimina un webhook.

delete.ts

await coffeemail.webhooks.delete('wh_123');

SDK Node

.listDeliveries

coffeemail.webhooks.listDeliveries(id, query?): Promise<CoffeeMailResponse<ListDeliveriesResponse>>

Lista el historial de intentos de entrega y estado del webhook.

listDeliveries.ts

const { data } = await coffeemail.webhooks.listDeliveries('wh_123', { status: 'failed' });

SDK Node

.rotateSecret

coffeemail.webhooks.rotateSecret(id): Promise<CoffeeMailResponse<RotateSecretResponse>>

Genera y rota el secreto criptográfico HMAC del webhook.

rotateSecret.ts

const { data } = await coffeemail.webhooks.rotateSecret('wh_123');console.log('Novo segredo:', data.secret);

SDK Node

.test

coffeemail.webhooks.test(id): Promise<CoffeeMailResponse<TestWebhookResponse>>

Dispara un evento simulado.

test.ts

const { data } = await coffeemail.webhooks.test('wh_123');

SDK Node

.verifySignature

coffeemail.webhooks.verifySignature(options): boolean

Valida el encabezado X-CoffeeMail-Signature (HMAC SHA-256 + timingSafeEqual).

verifySignature.ts

const isValid = coffeemail.webhooks.verifySignature({  payload: rawBody,  signature: req.headers['x-coffeemail-signature'],  secret: process.env.WEBHOOK_SECRET,});

coffeemail.Estadísticas

SDK Node

.get

coffeemail.stats.get(query?): Promise<CoffeeMailResponse<StatsResponse>>

Consulta métricas consolidadas y series temporales de la organización.

get.ts

const { data } = await coffeemail.stats.get({ period: 'last30d' });console.log('Total enviado:', data.totals.totalSent);