Skip to main content
SDKs · Node.js

Node.js SDK

Node 18+, TypeScript, ESM and CJS.

v0.3.0npmGitHub70 methodsPromise<{ data, error }>

Installation

Add the package to your project.

terminal
npm install @coffeemail/node

Configure the client

The key comes from COFFEEMAIL_API_KEY or the constructor. Use one key per environment.

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

Send an email

The send is queued and returns within milliseconds with the id and the queued status. Returns: Promise<{ data, error }>.

send
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',});

Handle errors

API errors arrive typed, with code, status and requestId; nothing is thrown on the common path.

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

Paginate

Lists return the page and a nextCursor; pass it as after to fetch the next one.

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

Verify webhooks

Validate x-webhook-signature against the raw request body, x-webhook-timestamp and x-webhook-idempotency-key. The default window is 300 seconds.

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

Method reference

Every public method, grouped by resource. Each row shows the endpoint it calls; open the API reference for fields and responses.

Emails8 methods

Endpoints →
MethodEndpoint called
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

Domains10 methods

Endpoints →
MethodEndpoint called
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

Templates12 methods

Endpoints →
MethodEndpoint called
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

Audiences and contacts10 methods

Endpoints →
MethodEndpoint called
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}

Campaigns6 methods

Endpoints →
MethodEndpoint called
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

Senders5 methods

Endpoints →
MethodEndpoint called
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}

Suppressions6 methods

Endpoints →
MethodEndpoint called
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 methods

Endpoints →
MethodEndpoint called
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

Statistics1 method

Endpoints →
MethodEndpoint called
coffeemail.stats.get()GET/stats

Validation1 method

Endpoints →
MethodEndpoint called
coffeemail.validation.validate()POST/validate