Pular para o conteúdo principal
SDKs · Node.js

SDK Node.js

Node 18+, TypeScript, ESM e CJS.

v0.3.0npmGitHub70 métodosPromise<{ data, error }>

Instalação

Adicione o pacote ao projeto.

terminal
npm install @coffeemail/node

Configurar o cliente

A chave vem de COFFEEMAIL_API_KEY ou do construtor. Use uma chave por ambiente.

cliente
import { CoffeeMail } from '@coffeemail/node'; const coffeemail = new CoffeeMail(process.env.COFFEEMAIL_API_KEY);

Enviar um email

O envio entra na fila e volta em milissegundos com o id e o status queued. Retorno: Promise<{ data, error }>.

enviar
const { data, error } = await coffeemail.emails.send({  from: 'Acme <pedidos@acme.com.br>',  to: 'ana@exemplo.com.br',  subject: 'Seu pedido #4821 foi enviado',  html: '<p>Chega amanhã.</p>',  idempotencyKey: 'pedido-4821-enviado',});

Tratar erros

Erros da API chegam tipados, com code, status e requestId; nada é lançado no caminho comum.

erros
const { data, error } = await coffeemail.emails.send(payload); if (error instanceof ValidationError) return showFieldErrors(error.details);if (error instanceof RateLimitError) return retryLater(error);if (error) throw error; console.log(data.id, data.status);

Paginar

Listas devolvem a página e o cursor nextCursor; passe-o em after para buscar a próxima.

paginar
const { data } = await coffeemail.emails.list({ limit: 100 }); for (const email of data?.emails ?? []) handle(email);const next = data?.nextCursor;

Verificar webhooks

Valide x-webhook-signature com o corpo bruto da requisição, x-webhook-timestamp e x-webhook-idempotency-key. A janela padrão é de 300 segundos.

webhook
import { Webhooks } from '@coffeemail/node'; const valid = Webhooks.verifySignature({  payload: rawBody,  headers: req.headers,  secret: process.env.COFFEEMAIL_WEBHOOK_SECRET,});

Referência de métodos

Todos os métodos públicos, agrupados por recurso. Cada linha mostra o endpoint chamado; abra a referência da API para ver campos e respostas.

Emails8 métodos

Endpoints →
MétodoEndpoint chamado
coffeemail.emails.send()POST/emails
coffeemail.emails.sendBatch()POST/emails/batch
coffeemail.emails.get()GET/emails/{id}
coffeemail.emails.list()GET/emails
coffeemail.emails.getEvents()GET/emails/{id}/events
coffeemail.emails.getTags()GET/emails/tags
coffeemail.emails.cancel()POST/emails/{id}/cancel
coffeemail.emails.resend()POST/emails/{id}/resend

Domínios10 métodos

Endpoints →
MétodoEndpoint chamado
coffeemail.domains.create()POST/domains
coffeemail.domains.list()GET/domains
coffeemail.domains.get()GET/domains/{id}
coffeemail.domains.verify()POST/domains/{id}/verify
coffeemail.domains.delete()DELETE/domains/{id}
coffeemail.domains.getHealth()POST/domains/{id}/health
coffeemail.domains.getWarmupStatus()GET/domains/{id}/warmup
coffeemail.domains.rotateDkim()POST/domains/{id}/dkim/rotate
coffeemail.domains.setTrackingDomain()PUT/domains/{id}/tracking-domain
coffeemail.domains.removeTrackingDomain()DELETE/domains/{id}/tracking-domain

Modelos12 métodos

Endpoints →
MétodoEndpoint chamado
coffeemail.templates.create()POST/templates
coffeemail.templates.list()GET/templates
coffeemail.templates.get()GET/templates/{id}
coffeemail.templates.update()PATCH/templates/{id}
coffeemail.templates.delete()DELETE/templates/{id}
coffeemail.templates.preview()POST/templates/preview
coffeemail.templates.format()POST/templates/format
coffeemail.templates.testRender()POST/templates/test-render
coffeemail.templates.testSend()POST/templates/{id}/test-send
coffeemail.templates.listVersions()GET/templates/{id}/versions
coffeemail.templates.getVersion()GET/templates/{id}/versions/{version}
coffeemail.templates.restoreVersion()POST/templates/{id}/versions/{version}/restore

Audiências e contatos10 métodos

Endpoints →
MétodoEndpoint chamado
coffeemail.audiences.create()POST/audiences
coffeemail.audiences.list()GET/audiences
coffeemail.audiences.get()GET/audiences/{id}
coffeemail.audiences.update()PUT/audiences/{id}
coffeemail.audiences.delete()DELETE/audiences/{id}
coffeemail.audiences.contacts.create()POST/audiences/{id}/contacts
coffeemail.audiences.contacts.list()GET/audiences/{id}/contacts
coffeemail.audiences.contacts.bulkAdd()POST/audiences/{id}/contacts/bulk
coffeemail.audiences.contacts.update()PUT/audiences/{id}/contacts/{contactId}
coffeemail.audiences.contacts.delete()DELETE/audiences/{id}/contacts/{contactId}

Campanhas6 métodos

Endpoints →
MétodoEndpoint chamado
coffeemail.broadcasts.create()POST/broadcasts
coffeemail.broadcasts.list()GET/broadcasts
coffeemail.broadcasts.get()GET/broadcasts/{id}
coffeemail.broadcasts.send()POST/broadcasts/{id}/send
coffeemail.broadcasts.cancel()POST/broadcasts/{id}/cancel
coffeemail.broadcasts.testSend()POST/broadcasts/{id}/test-send

Remetentes5 métodos

Endpoints →
MétodoEndpoint chamado
coffeemail.senders.create()POST/senders
coffeemail.senders.list()GET/senders
coffeemail.senders.verify()POST/senders/verify
coffeemail.senders.resendVerification()POST/senders/{id}/resend-verification
coffeemail.senders.delete()DELETE/senders/{id}

Supressões6 métodos

Endpoints →
MétodoEndpoint chamado
coffeemail.suppressions.list()GET/suppressions
coffeemail.suppressions.get()GET/suppressions/{id}
coffeemail.suppressions.create()POST/suppressions
coffeemail.suppressions.delete()DELETE/suppressions/{id}
coffeemail.suppressions.reactivate()POST/suppressions/{id}/reactivate
coffeemail.suppressions.bulkCreate()POST/suppressions/bulk

Webhooks11 métodos

Endpoints →
MétodoEndpoint chamado
coffeemail.webhooks.create()POST/webhooks
coffeemail.webhooks.list()GET/webhooks
coffeemail.webhooks.get()GET/webhooks/{id}
coffeemail.webhooks.update()PUT/webhooks/{id}
coffeemail.webhooks.toggle()PATCH/webhooks/{id}
coffeemail.webhooks.delete()DELETE/webhooks/{id}
coffeemail.webhooks.rotateSecret()POST/webhooks/{id}/rotate-secret
coffeemail.webhooks.listDeliveries()GET/webhooks/{id}/deliveries
coffeemail.webhooks.getDelivery()GET/webhooks/{id}/deliveries/{deliveryId}
coffeemail.webhooks.replayDelivery()POST/webhooks/{id}/deliveries/{deliveryId}/replay
coffeemail.webhooks.test()POST/webhooks/{id}/test

Estatísticas1 método

Endpoints →
MétodoEndpoint chamado
coffeemail.stats.get()GET/stats

Validação1 método

Endpoints →
MétodoEndpoint chamado
coffeemail.validation.validate()POST/validate