Node.js SDK

npm install @eusend_dev/sdk
# or
bun add @eusend_dev/sdk

import { Eusend } from '@eusend_dev/sdk'

const client = new Eusend('eu_live_...')
// or: const client = new Eusend() // reads EUSEND_API_KEY

const { data, error } = await client.emails.send({
  from: '[email protected]',
  to: '[email protected]',
  subject: 'Your order is confirmed',
  html: '<p>Thanks for your order!</p>',
  text: 'Thanks for your order!',
})

if (error) {
  console.error(error.name, error.message) // 'VALIDATION_ERROR' ...
} else {
  console.log(data.id) // 9a8b7c6d-...
}

import { WelcomeEmail } from './emails/welcome'

await client.emails.send({
  from: '[email protected]',
  to: '[email protected]',
  subject: 'Welcome',
  react: <WelcomeEmail name="Jane" />,
})

const { data } = await client.emails.send(
  { from: '[email protected]', to: '[email protected]', subject: 'Receipt', html: '<p>Thanks</p>' },
  { idempotencyKey: `receipt-${orderId}` },
)

const { data } = await client.batch.send([
  { from: '[email protected]', to: '[email protected]', subject: 'Hi Alice', html: '<p>Hi Alice</p>' },
  { from: '[email protected]', to: '[email protected]',   subject: 'Hi Bob',   html: '<p>Hi Bob</p>' },
])

console.log(data?.data) // [{ id: '9a8b7c6d-...' }, { id: '1f2e3d4c-...' }]

// Schedule for tomorrow morning
const { data } = await client.emails.send({
  from: '[email protected]',
  to: '[email protected]',
  subject: 'Your trial ends tomorrow',
  html: '<p>Reminder: your trial ends in 24 hours.</p>',
  scheduledAt: new Date(Date.now() + 24 * 60 * 60 * 1000),
})

// Reschedule
await client.emails.update(data!.id, {
  scheduledAt: '2026-07-04T09:00:00Z',
})

// Or cancel — the send is refunded to your monthly quota
await client.emails.cancel(data!.id)

// Get a single email with its delivery events
const { data } = await client.emails.get('9a8b7c6d-...')
console.log(data?.status)  // 'delivered'
console.log(data?.events)  // [{ type: 'sent', ... }, ...]

// List with filters
const { data: list } = await client.emails.list({ status: 'delivered', limit: 50 })
console.log(list?.data)        // array of emails
console.log(list?.nextCursor)  // pass as cursor for next page

// Add a domain and get DNS records
const { data } = await client.domains.create('yourdomain.com')
console.log(data?.dkim)   // { type: 'TXT', name: 'eusend._domainkey...', value: '...' }
console.log(data?.spf)    // { type: 'TXT', name: 'yourdomain.com', value: '...' }
console.log(data?.dmarc)  // { type: 'TXT', name: '_dmarc...', value: '...' }

// Trigger DNS verification
await client.domains.verify(domainId)

// List / get / delete
await client.domains.list()
await client.domains.get(domainId)
await client.domains.delete(domainId)

// Create a live key
const { data } = await client.apiKeys.create({ name: 'Production' })
console.log(data?.key) // eu_live_... — only returned once

// Create a test/sandbox key
const { data: test } = await client.apiKeys.create({ name: 'Sandbox', testMode: true })
// test.key → 'eu_test_...'

await client.apiKeys.list()
await client.apiKeys.delete(keyId)

// Create an HTML template with {{variable}} placeholders
const { data } = await client.templates.create({
  name: 'Welcome email',
  subject: 'Welcome, {{name}}!',
  html: '<h1>Hi {{name}}</h1><p>Welcome to {{product}}.</p>',
})

// Using React Email — SDK renders locally before sending
import { OrderConfirmation } from './emails/order-confirmation'

await client.templates.create({
  name: 'Order confirmation',
  subject: 'Order {{order_id}} confirmed',
  react: <OrderConfirmation />,
})

// Send using a template
await client.emails.send({
  from: '[email protected]',
  to: '[email protected]',
  templateId: data!.id,
  variables: { name: 'Jane', product: 'Acme' },
})

await client.templates.list()
await client.templates.get(templateId)
await client.templates.update(templateId, { name: 'New name' })
await client.templates.delete(templateId)

// Create an audience
const { data: aud } = await client.audiences.create('Newsletter')

// Add / upsert a contact
await client.audiences.createContact(aud!.id, {
  email: '[email protected]',
  firstName: 'Jane',
  lastName: 'Smith',
})

// Bulk import (up to 1,000 per call)
await client.audiences.batchCreateContacts(aud!.id, {
  contacts: [
    { email: '[email protected]', firstName: 'Alice' },
    { email: '[email protected]',   firstName: 'Bob' },
  ],
})

// List with filters
await client.audiences.listContacts(aud!.id, { subscribed: true, search: 'gmail.com' })

// Update / unsubscribe / delete
await client.audiences.updateContact(aud!.id, contactId, { unsubscribed: true })
await client.audiences.deleteContact(aud!.id, contactId)

await client.audiences.list()
await client.audiences.delete(aud!.id)

// Create a broadcast — HTML, a React Email component, or a saved template
import { MayNewsletter } from './emails/may-newsletter'

const { data } = await client.broadcasts.create({
  name: 'May newsletter',
  audienceId: '550e8400-e29b-41d4-a716-446655440000',
  from: '[email protected]',
  subject: 'May update',
  react: <MayNewsletter />,           // SDK renders to HTML locally
  // or: html: '<p>Hi {{first_name}}...</p>'
  // or: templateId: '7c9e6679-7425-40de-944b-e07fc1f90ae7'
})

// Send immediately
await client.broadcasts.send(data!.id)

// Or schedule for later
await client.broadcasts.send(data!.id, { scheduledAt: '2026-06-01T09:00:00.000Z' })

// Cancel a scheduled broadcast
await client.broadcasts.cancel(data!.id)

await client.broadcasts.list()
await client.broadcasts.get(broadcastId)   // includes delivery stats
await client.broadcasts.update(broadcastId, { subject: 'Updated subject' })
await client.broadcasts.delete(broadcastId)

// Subscribe to events
const { data } = await client.webhooks.create({
  url: 'https://yourapp.com/webhooks/eusend',
  events: ['email.sent', 'email.delivered', 'email.bounced', 'email.complained'],
  // or: events: ['*'] to receive everything
})
console.log(data?.secret) // signing secret — store it securely, only returned once

await client.webhooks.list()
await client.webhooks.get(webhookId)    // includes recent deliveries
await client.webhooks.update(webhookId, { events: ['email.bounced'] })
await client.webhooks.delete(webhookId)

import { createHmac, timingSafeEqual } from 'crypto'

async function verifyWebhook(req: Request, secret: string): Promise<boolean> {
  const id        = req.headers.get('webhook-id') ?? ''
  const timestamp = req.headers.get('webhook-timestamp') ?? ''
  const signature = req.headers.get('webhook-signature') ?? ''

  const body     = await req.text()
  const expected = 'v1,' + createHmac('sha256', secret)
    .update(`${id}.${timestamp}.${body}`)
    .digest('base64')

  return timingSafeEqual(Buffer.from(signature), Buffer.from(expected))
}

const { data, error } = await client.emails.send({ ... })

if (error) {
  console.error(error.name)       // 'MONTHLY_LIMIT_EXCEEDED'
  console.error(error.message)    // 'Monthly send limit exceeded'
  console.error(error.statusCode) // 429
}

import type {
  SendEmailOptions,
  Email,
  EmailStatus,
  EusendError,
  EusendResponse,
} from '@eusend_dev/sdk'