Documentation

Quickstart

Send your first transactional email in 5 minutes using the official Node SDK.

Prerequisites

Node.js 20+ installed.
A CoffeeMail account with at least one verified domain (see Verify your domain).
An API Key created in Dashboard → API Keys.

1. Install the SDK

.bash

npm install @coffeemail/node

@coffeemail/node ships in ESM and CommonJS with strict TypeScript and full typing.

2. Set your API key

.env.local

# .env.localCOFFEEMAIL_API_KEY=cm_live_your_key_here

Create an API key in Dashboard → API Keys. Use environment variables in production — never commit the key.

3. cURL alternative (no SDK)

send.sh

curl -X POST https://api.coffeemail.com.br/v1/product/emails \  -H "Authorization: Bearer $COFFEEMAIL_API_KEY" \  -H "Content-Type: application/json" \  -H "Accept-Language: en" \  -d '{    "from": "noreply@yourdomain.com",    "to": ["customer@example.com"],    "subject": "Welcome to CoffeeMail",    "html": "<h1>Welcome!</h1><p>Your account is active.</p>"  }' # {"id":"eml_8f3a2c1b","status":"queued","queuedAt":"2026-09-10T18:21:14.000Z"}

Same endpoint, no dependencies. Use when outside Node.js or for one-off scripts.

4. Send your first email

send-email.ts

import { CoffeeMail } from '@coffeemail/node'; const coffeemail = new CoffeeMail(process.env.COFFEEMAIL_API_KEY, {  locale: 'en',}); const { data, error } = await coffeemail.emails.send({  from: 'noreply@yourdomain.com',  to: 'customer@example.com',  subject: 'Welcome to CoffeeMail',  html: '<h1>Welcome!</h1><p>Your account is active.</p>',}); if (error) {  console.error(`Failed [${error.code}]:`, error.message);  process.exit(1);} console.log('Email queued:', data.id, data.status);

The SDK returns in the data, error pattern (Supabase/Resend style). Errors are typed (ValidationError, AuthenticationError, etc).

5. Track delivery

track-email.ts

const { data, error } = await coffeemail.emails.get('eml_8f3a2c1b');if (error) throw error;console.log('Current status:', data.status); // To see the full timeline (queued → sent → delivered):const { data: events } = await coffeemail.emails.getEvents('eml_8f3a2c1b');console.log(events);

data.status can be: queued, scheduled, processing, sent, delivered, bounced, complained, failed, skipped, cancelled.