@eusend_dev/sdk

eusend

Official Node.js SDK for the Eusend API — the EU-native transactional email platform.

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

Getting started

import { Eusend } from '@eusend_dev/sdk'

const client = new Eusend('eu_live_...')

Your API key can also be set via the EUSEND_API_KEY environment variable, in which case the constructor argument can be omitted:

const client = new Eusend()

Emails

Send an email

const { data, error } = await client.emails.send({
  // `from` accepts a bare email or a display-name form: `Acme <[e-mail]>`
  from: 'Acme <[e-mail]>',
  to: '[e-mail]',
  subject: 'Hello',
  html: '<p>Hello world</p>',
  text: 'Hello world',
})

console.log(data?.id) // 9a8b7c6d-5e4f-4a3b-8c1d-0e9f8a7b6c5d (UUID)

Options

Field	Type	Description
from	string	Sender address — a bare email or display-name form (Acme <[e-mail]>). Must be from a verified domain.
to	string | string[]	Recipient(s). Maximum 50.
cc	string | string[]	CC recipient(s). Maximum 50.
bcc	string | string[]	BCC recipient(s). Maximum 50.
replyTo	string | string[]	Reply-to address(es). Maximum 50.
subject	string	Email subject
html	string	HTML body
text	string	Plain text body
templateId	string	ID of a saved template
variables	Record<string, unknown>	Template variable substitutions
headers	Record<string, string>	Custom email headers, written into the outbound message. Header names and values may not contain line breaks.
trackOpens	boolean	Track open events (default: true)
trackClicks	boolean	Track click events (default: true)

At least one of html, react, text, or templateId is required.

Send with React Email

Pass a React Email component via the react field. The SDK renders it to HTML locally before sending — the JSX source never travels over the wire.

import { Eusend } from '@eusend_dev/sdk'
import { WelcomeEmail } from './emails/welcome'

const client = new Eusend()

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

Requires react and @react-email/render as peer dependencies:

npm install react @react-email/render

If you prefer to render yourself, pass the resulting HTML via html instead — useful when you want one rendered template to serve multiple sends.

Idempotent sends

Pass an idempotencyKey to safely retry without sending duplicates. If a request with the same key was already accepted, the original email ID is returned.

const { data } = await client.emails.send(
  {
    from: '[e-mail]',
    to: '[e-mail]',
    subject: 'Your receipt',
    html: '<p>Thanks for your order.</p>',
  },
  { idempotencyKey: `receipt-${orderId}` },
)

Send a batch

Up to 100 emails in a single request.

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

console.log(data?.data) // [{ id: '...' }, { id: '...' }]

Retrieve an email

const { data } = await client.emails.get('9a8b7c6d-5e4f-4a3b-8c1d-0e9f8a7b6c5d')

console.log(data?.status)  // 'delivered'
console.log(data?.events)  // [{ type: 'sent', ... }, { type: 'delivered', ... }]

List emails

const { data } = await client.emails.list({ limit: 20 })

console.log(data?.data)       // array of emails
console.log(data?.nextCursor) // pass as cursor to fetch the next page

Filtering

// By status
await client.emails.list({ status: 'delivered' })

// By sender
await client.emails.list({ from: '[e-mail]' })

// By recipient
await client.emails.list({ to: '[e-mail]' })

// Pagination
await client.emails.list({ limit: 50, cursor: data.nextCursor })

Available statuses: queued sending sent delivered bounced complained suppressed failed

Domains

Add a domain

const { data } = await client.domains.create('yourdomain.com')

// DNS records to add to your domain
console.log(data?.dkim)   // { type: 'TXT', name: 'eusend._domainkey.yourdomain.com', value: '...' }
console.log(data?.spf)    // { type: 'TXT', name: 'yourdomain.com', value: '...' }
console.log(data?.dmarc)  // { type: 'TXT', name: '_dmarc.yourdomain.com', value: '...' }

Verify a domain

After adding the DNS records, trigger verification:

await client.domains.verify(domainId)

List domains

const { data } = await client.domains.list()
// [{ id, name, status: 'verified', createdAt }]

Get a domain

const { data } = await client.domains.get(domainId)
// { id, name, dkimPublicKey, dkimSelector, status, createdAt, verifiedAt }

Delete a domain

await client.domains.delete(domainId)

API Keys

Create an API key

const { data } = await client.apiKeys.create({ name: 'Production' })

console.log(data?.key) // eu_live_... — only returned once, store it securely

Pass testMode: true to create a sandbox key. Emails sent with a test key are accepted and tracked but never delivered.

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

Scoping a key

permission defaults to 'full_access' — every resource. 'sending_access' limits the key to sending email (plus rescheduling and canceling a scheduled send); every other endpoint, including reading your email logs, returns 403 FORBIDDEN.

await client.apiKeys.create({ name: 'App server', permission: 'sending_access' })

A sending-access key can additionally be pinned to one sending domain. Sends from any other domain are rejected. domainId is only valid with permission: 'sending_access'.

await client.apiKeys.create({
  name: 'Billing service',
  permission: 'sending_access',
  domainId,
})

Deleting a domain revokes every key restricted to it.

List API keys

const { data } = await client.apiKeys.list()
// [{ id, name, prefix, testMode, permission, domainId, domainName, createdAt, lastUsedAt }]

The full key is never returned after creation — only the prefix (e.g. eu_live_Lx_e).

Delete an API key

await client.apiKeys.delete(keyId)

Audiences & Contacts

Create an audience

const { data } = await client.audiences.create('Newsletter')
const audienceId = data!.id

List audiences

const { data } = await client.audiences.list()
// [{ id, name, createdAt, contactCount }]

Delete an audience

await client.audiences.delete(audienceId)

Add a contact

const { data } = await client.audiences.createContact(audienceId, {
  email: '[e-mail]',
  firstName: 'Jane',
  lastName: 'Smith',
})

If a contact with that email already exists in the audience, it will be updated instead.

Bulk import contacts

Up to 1,000 contacts per call. Existing contacts are upserted.

const { data } = await client.audiences.batchCreateContacts(audienceId, {
  contacts: [
    { email: '[e-mail]', firstName: 'Alice' },
    { email: '[e-mail]', firstName: 'Bob' },
  ],
})

console.log(data?.count) // 2

List contacts

const { data } = await client.audiences.listContacts(audienceId, { limit: 100 })

// Filter by subscription status
await client.audiences.listContacts(audienceId, { subscribed: true })
await client.audiences.listContacts(audienceId, { subscribed: false })

// Search by email
await client.audiences.listContacts(audienceId, { search: 'gmail.com' })

// Pagination
await client.audiences.listContacts(audienceId, { cursor: data.nextCursor })

Get a contact

const { data } = await client.audiences.getContact(audienceId, contactId)
// { id, audienceId, email, firstName, lastName, status, unsubscribedAt, createdAt, updatedAt }

Update a contact

// Update name
await client.audiences.updateContact(audienceId, contactId, {
  firstName: 'Janet',
})

// Unsubscribe
await client.audiences.updateContact(audienceId, contactId, {
  unsubscribed: true,
})

// Re-subscribe
await client.audiences.updateContact(audienceId, contactId, {
  unsubscribed: false,
})

Delete a contact

await client.audiences.deleteContact(audienceId, contactId)

Suppressions

Addresses the account will not send to. Hard bounces and spam complaints are added automatically; these methods cover the ones you manage yourself. A send to a suppressed address is skipped and recorded with status suppressed; if every recipient is suppressed the send fails with ALL_SUPPRESSED.

Test-mode keys can read the list but not modify it.

List suppressions

const { data } = await client.suppressions.list({ reason: 'bounce', limit: 50 })
// { data: [{ id, email, reason, created_at }], next_cursor: null }

// Everything suppressed at one domain
await client.suppressions.list({ email: '@acme.com' })

Suppress an address

await client.suppressions.create({ email: '[e-mail]' })

If the address is already suppressed the existing entry is returned unchanged — a manual add never rewrites a real bounce or complaint.

Import a list

Up to 1,000 addresses per call. Items may be bare strings or objects, so a column lifted straight out of a CSV works as-is. Import before your first send when migrating, so addresses that already bounced elsewhere don't get a fresh attempt from a new IP.

const { data } = await client.suppressions.import([
  '[e-mail]',
  { email: '[e-mail]', reason: 'complaint' },
])

console.log(data?.count)              // written
console.log(data?.already_suppressed) // were already on the list
console.log(data?.duplicates)         // repeated rows collapsed

Remove an address

await client.suppressions.remove('[e-mail]') // or the entry id

Export

const { data: csv } = await client.suppressions.export()
// "email,reason,created_at\n..."

Templates

Templates let you define reusable email layouts with {{variable}} placeholders that are substituted at send time.

Variable values are HTML-escaped. A value you pass in variables is inserted as text, not markup — {{name}} with "<b>Jane</b>" renders the literal characters, not bold text. Put any HTML structure (links, formatting) in the template html itself, not in the variable values.

Create a template (HTML)

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

Create a template (React Email)

Pass a React Email component via react. The SDK renders it to HTML locally before submitting — the JSX source never travels over the wire.

import { OrderConfirmation } from './emails/order-confirmation'

const { data } = await client.templates.create({
  name: 'Order confirmation',
  subject: 'Your order {{order_id}} is confirmed',
  react: <OrderConfirmation />,
})

Use {{variable}} placeholders anywhere in your React component; they pass through to the rendered HTML and are substituted at send time when you provide variables. If you'd rather render yourself, pass html instead.

Send using a template

await client.emails.send({
  from: '[e-mail]',
  to: '[e-mail]',
  templateId: data!.id,
  variables: {
    first_name: 'Jane',
    order_id: 'ORD-1234',
  },
})

List, get, update, delete

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

Webhooks

Receive real-time events when email statuses change.

Create a webhook

const { data } = await client.webhooks.create({
  url: 'https://yourapp.com/webhooks/eusend',
  events: ['email.sent', 'email.delivered', 'email.bounced', 'email.complained'],
})

console.log(data?.secret) // signing secret — only returned once, store it securely

Pass '*' in the events array to subscribe to all events.

Available events: email.sent email.delivered email.bounced email.complained email.opened email.clicked

Endpoint requirements: the url must be a public http(s) endpoint — private, loopback, and internal addresses are rejected, both at creation and (after DNS resolution) before each delivery. Your endpoint must respond directly with a 2xx; redirects (3xx) are not followed and are treated as a failed delivery.

Verifying webhook signatures

Every delivery is signed with HMAC-SHA256. Verify the signature before processing:

import { createHmac, timingSafeEqual } from 'crypto'

async function verifyWebhook(req: Request, secret: string): Promise<boolean> {
  const webhookId = 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(`${webhookId}.${timestamp}.${body}`)
    .digest('base64')

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

List, get, update, delete

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)

Broadcasts

Send a single email to every contact in an audience.

Create a broadcast

const { data } = await client.broadcasts.create({
  name: 'May newsletter',
  audienceId: '550e8400-e29b-41d4-a716-446655440000',
  from: 'Sivert <[e-mail]>',
  subject: 'May update',
  html: '<p>Hi {{first_name}}, your monthly update is here...</p>',
})

You can also pass a React Email component via react, a saved template via templateId, or plain HTML. With react, the SDK renders to HTML locally before submitting:

import { MayNewsletter } from './emails/may-newsletter'

await client.broadcasts.create({
  name: 'May newsletter',
  audienceId: '550e8400-e29b-41d4-a716-446655440000',
  from: 'Sivert <[e-mail]>',
  subject: 'May update',
  react: <MayNewsletter />,
})

{{first_name}}, {{last_name}}, {{full_name}}, and {{email}} are automatically available per recipient. Custom variables can be defined on the broadcast and are merged with per-recipient data.

Unsubscribe handling

Broadcasts — and any single-recipient send whose recipient is a known audience contact — automatically include RFC 8058 one-click unsubscribe headers (List-Unsubscribe + List-Unsubscribe-Post: List-Unsubscribe=One-Click), so you satisfy Gmail/Yahoo bulk-sender requirements without any extra work. (Sends to multiple recipients at once omit the header, since a single unsubscribe link can't be attributed to one recipient.) Broadcasts additionally render a visible unsubscribe footer in the email body. An unsubscribe is recorded against the contact (unsubscribedAt) and excludes them from future broadcasts; transactional sends to that address still go through. You don't need to set these headers yourself.

Send a broadcast

await client.broadcasts.send(broadcastId)

Calling send on a paused broadcast resumes it — sending continues from where it stopped, skipping recipients already sent. A broadcast pauses if it hits your monthly or daily send limit, the sender domain becomes unverified, or platform-wide sending is paused.

Schedule a broadcast

await client.broadcasts.send(broadcastId, {
  scheduledAt: '2026-06-01T09:00:00.000Z',
})

Cancel a broadcast

await client.broadcasts.cancel(broadcastId)

List, get, update, delete

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)

Error handling

Every method returns { data, error, headers }. On success error is null; on failure data is null.

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
} else {
  console.log(data.id)
}

Error codes

Code	Status	Description
UNAUTHORIZED	401	Invalid or missing API key
FORBIDDEN	403	Action not allowed on your plan
NOT_FOUND	404	Resource not found
VALIDATION_ERROR	400	Invalid request body
BAD_REQUEST	400	Malformed request
CONFLICT	409	Resource already exists
RATE_LIMITED	429	Too many requests
MONTHLY_LIMIT_EXCEEDED	429	Monthly send quota reached
DAILY_LIMIT_EXCEEDED	429	Daily send ceiling reached (applies to all plans; ramps up as your account warms, resets midnight UTC)
PLAN_LIMIT_EXCEEDED	403	Feature not available on your plan
DOMAIN_NOT_VERIFIED	403	The sender domain is not verified for your organisation
SENDING_SUSPENDED	403	Sending suspended for your account (high bounce or complaint rate)
LIST_SEND_HELD	403	Past the unreviewed account's list-send allowance — the rest waits for review
BROADCAST_HELD	403	Broadcast used its unreviewed allowance; the remainder waits for review
ALL_SUPPRESSED	422	All recipients are on the suppression list
SERVICE_PAUSED	503	Sending is temporarily paused platform-wide
INTERNAL_ERROR	500	Server error
application_error	null	Network failure — request never reached the server

TypeScript

The SDK is written in TypeScript and ships with full type definitions. All request options, response shapes, and error codes are typed.

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

Requirements

• Node.js 18 or later (uses the native fetch API)
• An Eusend account and API key — eusend.dev