Documentation

SDK Node

v0.1.0

Referência completa do pacote @coffeemail/node. Cobertura total da API de Produto com retorno seguro no padrão data, error e erros tipados.

Instalação

.bash

npm i @coffeemail/node@0.1.0

Cliente

Instancia o cliente. A chave pode vir do construtor ou da variável de ambiente 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: 'pt-BR',  timeoutMs: 10_000,});

coffeemail.Emails

SDK Node

.send

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

Enfileira um email transacional.

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 até 100 emails em uma única chamada.

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>>

Detalha um email pelo 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 com filtros e paginação.

list.ts

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

SDK Node

.getEvents

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

Retorna a timeline de eventos do email.

getEvents.ts

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

SDK Node

.cancel

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

Cancela um email scheduled antes do envio.

cancel.ts

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

SDK Node

.resend

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

Reenvia um email existente.

resend.ts

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

coffeemail.Domínios

SDK Node

.create

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

Adiciona um domínio e retorna os 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 os domínios da organização.

list.ts

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

SDK Node

.get

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

Detalha um domínio.

get.ts

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

SDK Node

.verify

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

Executa a checagem DNS ativa.

verify.ts

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

SDK Node

.getHealth

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

Diagnóstico de reputação e blacklists.

getHealth.ts

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

SDK Node

.delete

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

Remove o domínio da organização.

delete.ts

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

coffeemail.Modelos

SDK Node

.create

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

Cadastra um template (handlebars ou 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 templates da organização.

list.ts

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

SDK Node

.get

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

Detalha um template.

get.ts

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

SDK Node

.update

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

Atualiza um template existente.

update.ts

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

SDK Node

.delete

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

Remove um template.

delete.ts

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

SDK Node

.format

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

Formata e indenta o código HTML/Handlebars do template.

format.ts

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

SDK Node

.testRender

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

Renderiza o template com sanitização de tags e injeção de variáveis.

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 os templates padrão pré-construídos da plataforma.

listStarters.ts

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

SDK Node

.getStarter

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

Detalha um template padrão por identificador ou slug.

getStarter.ts

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

coffeemail.Audiências

SDK Node

.create

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

Cria uma audiência.

create.ts

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

SDK Node

.list

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

Lista audiências.

list.ts

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

SDK Node

.get

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

Detalha uma audiência.

get.ts

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

SDK Node

.update

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

Atualiza o nome ou descrição de uma audiência.

update.ts

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

SDK Node

.delete

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

Remove uma audiência.

delete.ts

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

SDK Node

.contacts.create

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

Adiciona um contato à audiência.

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últiplos contatos em lote para uma audiência.

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 contatos de uma audiência.

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>>

Atualiza os atributos ou metadados de um contato.

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>>

Remove um contato da audiência.

contacts.delete.ts

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

coffeemail.Broadcasts

SDK Node

.create

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

Cria uma campanha para uma audiência.

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 campanhas.

list.ts

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

SDK Node

.get

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

Detalha uma campanha.

get.ts

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

SDK Node

.send

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

Dispara a campanha. Headers RFC 8058 são injetados automaticamente.

send.ts

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

SDK Node

.cancel

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

Cancela uma campanha ainda não enviada.

cancel.ts

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

coffeemail.Supressões

SDK Node

.list

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

Lista entradas da lista de supressão.

list.ts

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

SDK Node

.create

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

Adiciona manualmente uma 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 os detalhes e motivo de uma supressão específica.

get.ts

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

SDK Node

.delete

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

Remove uma entrada.

delete.ts

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

SDK Node

.reactivate

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

Reativa um destinatário suprimido para voltar a receber envios.

reactivate.ts

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

coffeemail.Webhooks

SDK Node

.create

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

Cadastra um 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 cadastrados.

list.ts

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

SDK Node

.get

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

Detalha um webhook.

get.ts

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

SDK Node

.update

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

Atualiza URL, eventos ou 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>>

Ativa ou pausa o recebimento de eventos no webhook.

toggle.ts

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

SDK Node

.delete

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

Remove um webhook.

delete.ts

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

SDK Node

.listDeliveries

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

Lista o histórico de tentativas de entrega e status do webhook.

listDeliveries.ts

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

SDK Node

.rotateSecret

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

Gera e rotaciona o segredo criptográfico HMAC do 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 um evento simulado.

test.ts

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

SDK Node

.verifySignature

coffeemail.webhooks.verifySignature(options): boolean

Valida o header 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.Estatísticas

SDK Node

.get

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

Consulta métricas consolidadas e séries históricas da organização.

get.ts

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