Documentation

Node SDK

v0.1.0

Full reference for the @coffeemail/node package. Complete coverage of the Product API with safe returns in the data, error pattern and typed errors.

Installation

.bash

npm i @coffeemail/node@0.1.0

Client

Instantiates the client. The key can come from the constructor or the COFFEEMAIL_API_KEY environment variable.

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

coffeemail.ts

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

coffeemail.Emails

SDK Node

.send

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

Enqueues a transactional email.

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

Sends up to 100 emails in a single call.

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

Returns email details by 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>>

Lists sent emails with filters and pagination.

list.ts

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

SDK Node

.getEvents

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

Returns the event timeline of the email.

getEvents.ts

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

SDK Node

.cancel

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

Cancels a scheduled email before it is sent.

cancel.ts

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

SDK Node

.resend

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

Resends an existing email.

resend.ts

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

coffeemail.Domains

SDK Node

.create

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

Adds a domain and returns the DNS records.

create.ts

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

SDK Node

.list

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

Lists the organization's domains.

list.ts

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

SDK Node

.get

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

Returns domain details.

get.ts

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

SDK Node

.verify

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

Runs active DNS verification.

verify.ts

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

SDK Node

.getHealth

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

Reputation and blacklist diagnostic.

getHealth.ts

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

SDK Node

.delete

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

Removes the domain from the organization.

delete.ts

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

coffeemail.Templates

SDK Node

.create

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

Registers a template (handlebars or 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>>

Lists the organization's templates.

list.ts

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

SDK Node

.get

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

Returns template details.

get.ts

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

SDK Node

.update

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

Updates an existing template.

update.ts

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

SDK Node

.delete

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

Removes a template.

delete.ts

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

SDK Node

.format

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

Formats and indents template HTML/Handlebars code.

format.ts

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

SDK Node

.testRender

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

Renders template with tag sanitization and variable interpolation.

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

Lists pre-built starter templates provided by the platform.

listStarters.ts

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

SDK Node

.getStarter

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

Retrieves a starter template by identifier or slug.

getStarter.ts

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

coffeemail.Audiences

SDK Node

.create

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

Creates an audience.

create.ts

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

SDK Node

.list

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

Lists audiences.

list.ts

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

SDK Node

.get

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

Returns audience details.

get.ts

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

SDK Node

.update

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

Updates an audience name or description.

update.ts

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

SDK Node

.delete

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

Removes an audience.

delete.ts

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

SDK Node

.contacts.create

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

Adds a contact to the audience.

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

Imports multiple contacts in batch to an audience.

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

Lists audience contacts.

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

Updates contact attributes or metadata.

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

Removes a contact from the audience.

contacts.delete.ts

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

coffeemail.Broadcasts

SDK Node

.create

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

Creates a campaign for an audience.

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

Lists campaigns.

list.ts

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

SDK Node

.get

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

Returns campaign details.

get.ts

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

SDK Node

.send

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

Sends the campaign. RFC 8058 headers are injected automatically.

send.ts

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

SDK Node

.cancel

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

Cancels a campaign that has not been sent yet.

cancel.ts

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

coffeemail.Suppressions

SDK Node

.list

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

Lists suppression list entries.

list.ts

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

SDK Node

.create

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

Manually adds an entry.

create.ts

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

SDK Node

.get

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

Retrieves details and reason for a specific suppression.

get.ts

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

SDK Node

.delete

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

Removes an entry.

delete.ts

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

SDK Node

.reactivate

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

Reactivates a suppressed recipient to resume deliveries.

reactivate.ts

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

coffeemail.Webhooks

SDK Node

.create

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

Registers an HTTPS endpoint.

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

Lists registered webhooks.

list.ts

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

SDK Node

.get

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

Returns webhook details.

get.ts

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

SDK Node

.update

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

Updates URL, events or 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>>

Activates or pauses webhook event delivery.

toggle.ts

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

SDK Node

.delete

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

Removes a webhook.

delete.ts

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

SDK Node

.listDeliveries

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

Lists webhook delivery attempt logs and statuses.

listDeliveries.ts

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

SDK Node

.rotateSecret

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

Rotates and returns a new HMAC secret for the 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>>

Triggers a simulated event.

test.ts

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

SDK Node

.verifySignature

coffeemail.webhooks.verifySignature(options): boolean

Validates the X-CoffeeMail-Signature header (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.Statistics

SDK Node

.get

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

Queries aggregated metrics and time series for the organization.

get.ts

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