sendrix-node

Official Node.js SDK for the Sendrix email marketing API.

Requirements: Node.js ≥ 18 (uses built-in fetch). Zero runtime dependencies.

Installation

npm install sendrix-node

Quick Start

import { Sendrix } from 'sendrix-node';

const client = new Sendrix({
  apiKey: process.env.SENDRIX_API_KEY!,
});

// Add a subscriber — they'll receive a confirmation email and be 'unconfirmed' until they click it.
const subscriber = await client.subscribers.add(listId, {
  email: '[email protected]',
  name: 'Jane Smith',
});
console.log(subscriber.status); // 'unconfirmed'

// Trigger an automation with personalised data
await client.automations.trigger(automationId, {
  email: '[email protected]',
  data: { plan_name: 'Free', usage_pct: 84 },
});

API Reference

client.lists

| Method | Description | |---|---| | list() | List all mailing lists | | get(listId) | Get a single list | | create({ name, description? }) | Create a new list | | update(listId, params) | Update name or description | | delete(listId) | Delete list and all subscribers (Full Access key required) |

client.subscribers

| Method | Description | |---|---| | list(listId, { status?, limit?, offset? }) | List subscribers | | add(listId, { email, name?, trusted? }) | Add a subscriber | | lookup(listId, email) | Find by email (returns null if not found) | | unsubscribe(listId, subscriberId) | Unsubscribe (keeps record) | | remove(listId, subscriberId) | Delete permanently (Full Access) |

Subscribers go through the normal confirmation email flow. See App Integration if you're adding users from your own app's registration handler.

client.automations

| Method | Description | |---|---| | list(listId) | List automations for a list | | get(automationId) | Get a single automation | | trigger(automationId, { email?, data? }) | Enrol subscriber (or all confirmed subscribers if email omitted) (Full Access) | | activate(automationId) | Activate automation (Full Access) |

Merge tags: Values in the data object are available in email templates as {{trigger.key}}.

await client.automations.trigger(nudgeAutomationId, {
  email: '[email protected]',
  data: {
    plan_name: 'Free',
    usage_pct: 84,
    monthly_limit: 1000,
  },
});
// In the email: "You've used {{trigger.usage_pct}}% of your {{trigger.monthly_limit}} monthly sends."

client.broadcasts

| Method | Description | |---|---| | list(listId) | List broadcasts | | get(broadcastId) | Get a single broadcast | | create(listId, { subject, content? }) | Create a draft | | send(broadcastId) | Send immediately (Full Access) | | schedule(broadcastId, sendAt) | Schedule for a future date (Full Access) | | cancel(broadcastId) | Revert scheduled broadcast to draft |

client.webhooks

| Method | Description | |---|---| | list() | List registered webhooks | | get(webhookId) | Get a single webhook | | create({ url, events?, secret? }) | Register a webhook | | update(webhookId, params) | Update URL, events, or enabled status | | delete(webhookId) | Delete webhook (Full Access) | | test(webhookId) | Send a test delivery |

Event types: subscriber.confirmed, subscriber.unsubscribed, subscriber.bounced, subscriber.complained, broadcast.sent, broadcast.opened, broadcast.clicked

Verify signatures:

import crypto from 'crypto';

function verifySignature(rawBody: Buffer, signature: string, secret: string): boolean {
  const expected = crypto.createHmac('sha256', secret).update(rawBody).digest('hex');
  return crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(signature));
}

client.account

| Method | Description | |---|---| | getUsage() | Email quota for current billing period |

Error Handling

All methods throw SendrixError on API errors:

import { Sendrix, SendrixError } from 'sendrix-node';

try {
  await client.subscribers.add(listId, { email: 'bad' });
} catch (err) {
  if (err instanceof SendrixError) {
    console.error(err.status);   // 400
    console.error(err.code);     // 'VALIDATION_ERROR'
    console.error(err.message);  // 'Invalid request body'
    console.error(err.details);  // [{ param: 'email', issue: 'invalid email address format' }]
  }
}

Express Integration Example

import { Sendrix } from 'sendrix-node';

const sendrix = new Sendrix({ apiKey: process.env.SENDRIX_API_KEY! });
const LIST_ID = Number(process.env.SENDRIX_LIST_ID!);

async function syncUserToSendrix(email: string, name: string): Promise<void> {
  // Non-blocking — never throw, never block signup
  sendrix.subscribers.add(LIST_ID, { email, name }).catch((err) => {
    if (err?.code === 'already_subscribed') return; // idempotent
    console.warn('[Sendrix] Failed to sync user:', err?.message);
  });
}

// In your registration handler:
app.post('/register', async (req, res) => {
  const user = await db.createUser(req.body.email, req.body.password);
  syncUserToSendrix(user.email, user.name); // fire-and-forget
  res.json({ ok: true });
});

App Integration — Your app's signup flow

By default, every subscriber you add via the API receives a confirmation email and stays in an unconfirmed state until they click the link. This is the right behaviour for most cases — it proves the address is real and that the person actually wants to hear from you.

When you're adding users from your own app's registration flow, that confirmation step is redundant: the person just signed up for your product and handed you their email directly. Mark the list as an App Integration in Sendrix (Settings → List Settings → App Integration) and subscribers are confirmed immediately, with no extra email.

// Once the list is marked as an App Integration in the Sendrix UI,
// subscribers added from your registration handler are confirmed immediately.
const subscriber = await client.subscribers.add(listId, {
  email: req.body.email,
  name: req.body.name,
});
// subscriber.status === 'confirmed'

This is not a licence to add anyone you like. App Integration mode exists for one narrow use case: users who signed up for your product and gave you their email address as part of that process. Adding purchased lists, scraped addresses, event attendees, business card contacts, or anyone who didn't explicitly register with you is a violation of Sendrix's Terms of Service and, depending on your jurisdiction, illegal under GDPR, CAN-SPAM, CASL, and similar laws. Violations can get your Sendrix account terminated and expose you to significant legal liability. When in doubt, use the default confirmation flow — it protects you and your subscribers.

TypeScript

Full TypeScript support with declaration files included. All types are exported from sendrix-node:

import { Sendrix, SendrixError, type Subscriber, type WebhookEventType } from 'sendrix-node';