sendridge

sendridge

Official Node.js SDK for Sendridge — transactional email for developers.

• Typed end to end — full TypeScript definitions for every request and response.
• Zero dependencies — uses the fetch built into Node 18+.
• Dual module support — works with both import (ESM) and require (CommonJS).
• Typed errors — every failure maps to a specific error class you can catch.
• Safe retries — idempotent reads retry automatically with backoff; sends are never retried, so an email can never be delivered twice by the SDK.

Installation

npm install sendridge

Requires Node.js 18 or newer.

Setup

Grab an API key from your Sendridge dashboard (API Keys → Create key), then set it in your environment:

SENDRIDGE_API_KEY=sr_xxxxxxxxxxxxxxxx

Server-side only. Your API key grants full sending access to your account. Never use this SDK in browser code or expose the key to clients.

Quickstart

import { Sendridge } from "sendridge";

const sendridge = new Sendridge(); // reads SENDRIDGE_API_KEY

const { id } = await sendridge.emails.send({
  from: "you@yourdomain.com", // domain must be verified in your dashboard
  to: "customer@example.com",
  subject: "Welcome aboard!",
  html: "<h1>Hello 👋</h1><p>Thanks for signing up.</p>",
});

console.log(`Queued email ${id}`);

CommonJS works too:

const { Sendridge } = require("sendridge");

Usage

Send an email

const result = await sendridge.emails.send({
  from: "billing@yourdomain.com",
  to: ["a@example.com", "b@example.com"], // up to 50 recipients
  subject: "Your invoice",
  html: "<p>Invoice attached below.</p>",
  text: "Invoice attached below.",       // plain-text alternative
  replyTo: "support@yourdomain.com",
  tags: { type: "invoice" },
  metadata: { invoiceId: "INV-2026-0042" },
});
// result: { id, status: "queued", to, from, subject, createdAt }

Sending is asynchronous — the API queues the message and returns immediately with status: "queued".

Track an email

const email = await sendridge.emails.get(result.id);
// email.status: "queued" | "sending" | "sent" | "delivered" | "bounced" | "failed" | "complained"
// email.openCount, email.clickCount, email.errorMessage, ...

List your emails

const { data, pagination } = await sendridge.emails.list({ page: 1, limit: 20 });

Error handling

Every failure throws a subclass of SendridgeError:

import {
  Sendridge,
  SendridgeError,
  ValidationError,     // 400 — bad payload; check err.details for field errors
  AuthenticationError, // 401 — missing/invalid/revoked/expired API key
  PermissionError,     // 403 — e.g. sending domain not verified, plan restriction
  NotFoundError,       // 404 — unknown email id
  RateLimitError,      // 429 — plan or per-key rate limit hit
  ServerError,         // 5xx — Sendridge-side problem
  TimeoutError,        // request exceeded the timeout
  NetworkError,        // DNS/connection failure
} from "sendridge";

try {
  await sendridge.emails.send({ /* ... */ });
} catch (err) {
  if (err instanceof RateLimitError) {
    // back off and try again later
  } else if (err instanceof ValidationError) {
    console.error(err.message, err.details);
  } else if (err instanceof SendridgeError) {
    console.error(`Sendridge error ${err.statusCode}: ${err.message}`);
  } else {
    throw err;
  }
}

Configuration

const sendridge = new Sendridge("sr_...", {
  baseUrl: "https://api.sendridge.com", // override for self-hosted / local dev
  timeoutMs: 30_000,                    // per-request timeout (default 30s)
  maxRetries: 2,                        // GET-only automatic retries (default 2)
});

Documentation

Full API reference and guides: https://sendridge.com/docs

License

MIT