Skip to content

Documentation

Send your first email.

Verify a domain, create an API key, and send — through the typed Node SDK or straight over HTTP from any language.

Introduction

Sendridge is a transactional email platform for developers. You verify a sending domain, grab an API key, and send email through a simple HTTPS API — Sendridge handles queuing, delivery, retries, and tracking (opens, clicks, bounces, complaints).

There are two ways to integrate: the official Node.js SDK (recommended) or the REST API directly from any language.

Quickstart

  1. 1Create an account and confirm your email address using the link we send you. Your dashboard opens once you do — if the email doesn't arrive, check your spam folder or use Resend verification email on the verification page.
  2. 2Verify your sending domain (Dashboard → Domains). Sendridge gives you DNS records to add; verification usually completes in minutes.
  3. 3Create an API key (Dashboard → API Keys). Keys look like sr_… and are shown once — store yours securely.
  4. 4Install the SDK and send a test email to your registered address:
Shell
npm install sendridge
send.ts
import { Sendridge } from "sendridge";

const sendridge = new Sendridge(process.env.SENDRIDGE_API_KEY);

const { id } = await sendridge.emails.send({
  from: "Acme <you@yourdomain.com>",
  to: "your-registered-email@example.com",
  subject: "Welcome aboard!",
  html: "<h1>Hello 👋</h1><p>Thanks for signing up.</p>",
});

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

Sending is asynchronous: the API responds immediately with status: "queued", then Sendridge delivers in the background. Use emails.get(id) to follow the delivery status.

Sandbox and going live

Every new account starts in sandbox mode. You can send test emails from a verified domain to your own registered email address while setting up. Sends to other recipients become available after your account and sending domain are approved.

Before you can request live sending, confirm your account email, verify a domain's ownership and DKIM records, complete your organisation name and postal address in Settings, and send a test email from that verified domain to your registered address. Custom MAIL FROM is recommended but does not block your request.

The Sending access page shows your checklist and the Request live sending form. Tell us what you'll send, your business type, and your HTTPS website, then accept the sending rules. Reviews usually take a few minutes; you can keep testing with your own address while you wait.

If your request is rejected, we'll show the reason in your dashboard and email it to you. Fix the issue and resubmit the form. When your account is approved, the verified domains included in that approval can send to other recipients. A domain you verify later needs its own quick approval from the Domains page; your already approved domains keep working while it is reviewed.

Authentication

Every request is authenticated with your API key as a Bearer token. The SDK does this for you; for direct REST calls, send the header yourself:

Shell
Authorization: Bearer sr_xxxxxxxxxxxxxxxx

Best practice: keep the key in an environment variable. The SDK automatically reads SENDRIDGE_API_KEY when you don't pass a key to the constructor.

Each key has permissions you choose when you create it, and can change later on the API keys page: read (every GET), write (contacts, segments, topics, templates), sendEmail (sending, batches, scheduling, sharing), broadcasts (creating, changing and sending broadcasts) and webhooks. New keys have the first three; broadcasts and webhooks stay off until you turn them on, so a leaked key can't email your whole audience. A request the key isn't allowed to make gets 403.

Keys can also be restricted to IP allowlists, given expiry dates and per-minute rate caps, and rotated at any time. A rotated or revoked key stops working immediately.

SDK — Installation

Shell
npm install sendridge

Requires Node.js 18+, or any runtime with fetch — including the Next.js Edge runtime and Nuxt's edge presets. The package ships TypeScript types, works with both import (ESM) and require (CommonJS), and has zero runtime dependencies. Framework guides: Next.js and Nuxt.

TypeScript
// ESM / TypeScript
import { Sendridge } from "sendridge";

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

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

SDK — Send an email

TypeScript
const result = await sendridge.emails.send({
  from: "Acme Billing <billing@yourdomain.com>", // name shown in the inbox; domain must be verified
  to: ["a@example.com", "b@example.com"], // string or array, max 50
  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: "665f1c2e9b1d2a0012345678",
//   status: "queued",
//   to: ["a@example.com", "b@example.com"],
//   from: "Acme Billing <billing@yourdomain.com>",
//   subject: "Your invoice",
//   createdAt: "2026-07-15T10:30:00.000Z"
// }
FieldTypeRequiredDescription
fromstringYesSender, as "Your Name <you@yourdomain.com>" or a bare address. Inboxes show the name as the sender; without one they show the part before the @ (e.g. "info"). The domain must be verified in your dashboard.
tostring | string[]YesOne recipient, or up to 50.
subjectstringYesSubject line (max 998 chars).
htmlstringOne of html/textHTML body.
textstringOne of html/textPlain-text body.
replyTostringNoReply-To address. Accepts the same "Name <address>" form.
tagsRecord<string, string>NoString tags for your own filtering.
metadataRecord<string, unknown>NoArbitrary JSON stored with the email.

SDK — Retrieve an email

TypeScript
const email = await sendridge.emails.get("665f1c2e9b1d2a0012345678");

// email.status is one of:
// "queued" | "sending" | "sent" | "delivered" | "bounced" | "failed" | "complained"

console.log(email.status, email.openCount, email.clickCount);

The returned object includes the full body (html/text), delivery status, open and click counts, your tags and metadata, and an errorMessage when delivery failed.

SDK — List emails

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

for (const email of data) {
  console.log(email.id, email.subject, email.status);
}
// pagination: { page: 1, limit: 20, total: 132 }

SDK — Schedule, attach and batch

Available from version 1.3.0.

TypeScript
// Send later (up to 30 days ahead), then move or cancel it.
const { id } = await sendridge.emails.send({ ...message, scheduledAt: new Date("2026-11-01T09:00:00Z") });
await sendridge.emails.update(id, { scheduledAt: "2026-11-02T09:00:00Z" });
await sendridge.emails.cancel(id);

// Attach files (up to 10, 10 MB in all): bytes or a base64 string.
await sendridge.emails.send({
  ...message,
  attachments: [{ filename: "invoice.pdf", content: pdfBytes, contentType: "application/pdf" }],
});
const files = await sendridge.emails.attachments.list(id);
const bytes = await sendridge.emails.attachments.download(id, files[0].id);

// Up to 100 emails in one request; each result says whether it was queued.
const results = await sendridge.emails.batch([welcomeAda, welcomeBen]);

// A link anyone can open to view one email, and turning such links off.
const { url } = await sendridge.emails.share(id, { expiresInHours: 48 });
await sendridge.emails.revokeShares(id);

SDK — Contacts

Keep your Sendridge audience in step with your site. Contacts are addressed by id or by email address, and create creates the contact or updates the one with that email, so it is safe to call on every signup. Available from version 1.1.0.

TypeScript
const { contact, created } = await sendridge.contacts.create({
  email: "ada@example.com",
  firstName: "Ada",
  tags: ["newsletter"],
  consentEvidence: "Newsletter form on example.com", // recorded with the contact
});

const ada = await sendridge.contacts.get("ada@example.com");
await sendridge.contacts.update("ada@example.com", { tags: ["newsletter", "vip"] });
await sendridge.contacts.update("ada@example.com", { unsubscribed: true });
await sendridge.contacts.remove("ada@example.com");

// One page, newest first, or every contact:
const { data, nextCursor } = await sendridge.contacts.list({ limit: 100, tag: "vip" });
for await (const c of sendridge.contacts.iterate({ unsubscribed: false })) {
  console.log(c.email);
}

// Many at once: arrays over 1,000 are sent in chunks, with a result per row.
const result = await sendridge.contacts.batch(rows, {
  consentEvidence: "Opted in at checkout",
  mergeTags: true, // add tags instead of replacing them
});
console.log(result.created, result.updated, result.failed);

SDK — Topics and segments

Topics are the kinds of email you send. People can drop one from the unsubscribe page, or with a topic broadcast's own unsubscribe link, without leaving your list. Segments are saved rules that pick contacts for a broadcast. Available from version 1.2.0.

TypeScript
const news = await sendridge.topics.create({ name: "Product news", description: "What we shipped, monthly" });
const digest = await sendridge.topics.create({ name: "Weekly digest", defaultSubscription: "opt_in" });

// A signup form with a "send me the weekly digest" checkbox:
await sendridge.contacts.create({
  email: "ada@example.com",
  topics: [{ id: digest.id, subscribed: true }],
});

const vips = await sendridge.segments.create({
  name: "Acme VIPs",
  conditions: [
    { field: "tag", operator: "has", value: "vip" },
    { field: "email", operator: "ends_with", value: "@acme.com" },
  ],
});
console.log(vips.contactCount);

// Try rules without saving them:
const { contactCount, sample } = await sendridge.segments.preview({
  match: "any",
  conditions: [{ field: "topic", operator: "subscribed", value: news.id }],
});

SDK — Broadcasts and templates

One email to many contacts: everyone subscribed, a tag or a segment, optionally only the people who receive a topic. Creating, changing and sending need the key's broadcasts permission. Available from version 1.3.0.

TypeScript
const draft = await sendridge.broadcasts.create({
  subject: "October news",
  fromEmail: "news@yourdomain.com",
  fromName: "Acme",
  html: "<p>Hi {{contact.first_name|there}}</p>",
  segmentId: vips.id, // or tag: "vip"; neither sends to everyone subscribed
});

await sendridge.broadcasts.test(draft.id, "you@yourdomain.com");
await sendridge.broadcasts.send(draft.id);                                         // now
await sendridge.broadcasts.send(next.id, { scheduledAt: "2026-11-03T08:00:00Z" }); // later
await sendridge.broadcasts.cancel(next.id);                                        // back to a draft

// After sending:
const { data } = await sendridge.broadcasts.recipients(draft.id, { status: "bounced" });
const links = await sendridge.broadcasts.links(draft.id);
const { delivered, opened, rates } = await sendridge.broadcasts.metrics(draft.id);

// Templates: broadcasts made from one use its published version.
await sendridge.templates.publish(template.id);
await sendridge.broadcasts.create({ subject: "November news", fromEmail: "news@yourdomain.com", templateId: template.id });

const metrics = await sendridge.metrics.emails({ from: "2026-10-01" });

SDK — Verify webhooks

verifyWebhook checks that a request came from Sendridge and returns the typed event. Pass the raw body exactly as received: a re-serialised object breaks the signature. It uses Web Crypto, so it works on Node 18+ and on edge runtimes.

TypeScript
// app/api/sendridge/route.ts
import { verifyWebhook, WebhookVerificationError } from "sendridge";

export async function POST(request: Request) {
  try {
    const event = await verifyWebhook({
      payload: await request.text(),
      headers: request.headers,
      secret: process.env.SENDRIDGE_WEBHOOK_SECRET!,
    });
    if (event.type === "contact.unsubscribed" || event.type === "contact.suppressed") {
      // stop emailing event.data.email from your own systems too
    }
    return new Response(null, { status: 204 });
  } catch (err) {
    if (err instanceof WebhookVerificationError) {
      return new Response(err.message, { status: 400 });
    }
    throw err;
  }
}
TypeScript
// Express: keep the body raw for this route
app.post("/webhooks/sendridge", express.raw({ type: "application/json" }), async (req, res) => {
  try {
    const event = await verifyWebhook({ payload: req.body, headers: req.headers, secret });
    // handle event.type ...
    res.sendStatus(204);
  } catch {
    res.sendStatus(400);
  }
});

signWebhookForTest signs a payload the same way, so you can test your handler without waiting for a real event.

SDK — Error handling

Every failure throws a typed subclass of SendridgeError, so you can branch on the exact failure mode:

TypeScript
import {
  SendridgeError,
  ValidationError,     // 400 — bad payload; err.details has field errors
  AuthenticationError, // 401 — missing / invalid / revoked / expired key
  PermissionError,     // 403 — e.g. sandbox or domain approval restriction
  NotFoundError,       // 404 — unknown email id or contact
  ConflictError,       // 409 — e.g. resubscribing a contact who unsubscribed
  RateLimitError,      // 429 — rate limit or quota exceeded
  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, then try again
  } else if (err instanceof ValidationError) {
    console.error(err.message, err.details);
  } else if (err instanceof SendridgeError) {
    console.error(err.statusCode, err.message);
  } else {
    throw err;
  }
}

Idempotent reads (get, list) automatically retry up to twice on network failures and 5xx/429 responses, with exponential backoff. Sends are never retried.

A send blocked by sandbox mode (sandbox_restricted) or a domain awaiting approval (domain_not_approved) throws PermissionError. Its messageexplains the restriction and where to request approval.

SDK — Configuration

TypeScript
const sendridge = new Sendridge("sr_...", {
  baseUrl: "https://api.sendridge.com", // override for local dev or staging
  timeoutMs: 30_000,                    // per-request timeout (default 30s)
  maxRetries: 2,                        // GET-only automatic retries (default 2)
});
FieldTypeRequiredDescription
SENDRIDGE_API_KEYenvNoUsed when no key is passed to the constructor.
SENDRIDGE_BASE_URLenvNoUsed when no baseUrl option is passed — point the SDK at a local or staging API.

Every request is sent with cache: "no-store", so framework fetch caches never serve a stale email status. The SDK refuses to start in a browser, where your API key would be visible to every visitor.

Next.js

Works in the App Router and the Pages Router, on the Node.js and Edge runtimes. Use it in server code — route handlers, server actions, getServerSideProps — never in a "use client" component. Add your key to .env.local:

Shell
SENDRIDGE_API_KEY=sr_xxxxxxxxxxxxxxxx

A route handler:

TypeScript
// app/api/send/route.ts
import { Sendridge } from "sendridge";

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

export async function POST(request: Request) {
  const { email } = await request.json();

  const { id } = await sendridge.emails.send({
    from: "Acme <hello@yourdomain.com>",
    to: email,
    subject: "Welcome to Acme",
    html: "<p>Thanks for signing up.</p>",
  });

  return Response.json({ id });
}

Or a server action:

TypeScript
// app/actions.ts
"use server";

import { Sendridge } from "sendridge";

const sendridge = new Sendridge();

export async function sendWelcome(formData: FormData) {
  const email = String(formData.get("email"));

  await sendridge.emails.send({
    from: "Acme <hello@yourdomain.com>",
    to: email,
    subject: "Welcome to Acme",
    html: "<p>Thanks for signing up.</p>",
  });
}

To run a route on the Edge runtime, add export const runtime = "edge"; to it. Nothing else changes. Creating the client at the top of a file is safe: a missing key is only reported when you send, so next build never fails because a build machine lacks SENDRIDGE_API_KEY.

Nuxt

Works with Nuxt 3 and Nuxt 4 in server routes, on Node and edge deployment presets. Keep the key in server-only runtime config:

TypeScript
// nuxt.config.ts
export default defineNuxtConfig({
  runtimeConfig: {
    // Server-only. Set it with the NUXT_SENDRIDGE_API_KEY environment variable.
    sendridgeApiKey: "",
  },
});
Shell
NUXT_SENDRIDGE_API_KEY=sr_xxxxxxxxxxxxxxxx

Then send from a server route:

TypeScript
// server/api/send.post.ts
import { Sendridge } from "sendridge";

export default defineEventHandler(async (event) => {
  const { email } = await readBody<{ email: string }>(event);
  const sendridge = new Sendridge(useRuntimeConfig(event).sendridgeApiKey);

  const { id } = await sendridge.emails.send({
    from: "Acme <hello@yourdomain.com>",
    to: email,
    subject: "Welcome to Acme",
    html: "<p>Thanks for signing up.</p>",
  });

  return { id };
});

Sync your site's signups

Your site and Sendridge each keep a list of who wants your emails. These steps keep the two in step in both directions.

  1. 1Create an API key under API keys and keep it on your server as SENDRIDGE_API_KEY.
  2. 2When someone signs up, call sendridge.contacts.create() with their email, name and a consentEvidence note saying how they agreed (for example, the form and page). Repeats are harmless.
  3. 3When someone unsubscribes on your site, call sendridge.contacts.update(email, { unsubscribed: true }).
  4. 4To hear about changes made in Sendridge (the unsubscribe link in an email, a bounce or complaint, an edit in the dashboard), add an endpoint under Developer tools › Webhooks, keep its signing secret as SENDRIDGE_WEBHOOK_SECRET, and verify each request with verifyWebhook(). Webhooks are included in the Starter plan and above.
  5. 5Bring your existing list across once with sendridge.contacts.batch(), or upload a CSV under Audience › Import CSV.

REST API — Overview

Prefer another language? The REST API is the same surface the SDK wraps. All endpoints accept and return JSON.

Text
Base URL:  https://api.sendridge.com
Auth:      Authorization: Bearer sr_xxxxxxxxxxxxxxxx

Successful responses wrap the payload in a data field; errors return { error, message, code?, details? }.

POST /v1/emails/send

Queues an email for delivery. Responds 202 Accepted.

POST /v1/emails/send
curl -X POST https://api.sendridge.com/v1/emails/send \
  -H "Authorization: Bearer $SENDRIDGE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "from": "you@yourdomain.com",
    "to": "customer@example.com",
    "subject": "Welcome!",
    "html": "<h1>Hello</h1>"
  }'
202 Accepted
{
  "data": {
    "id": "665f1c2e9b1d2a0012345678",
    "status": "queued",
    "to": ["customer@example.com"],
    "from": "you@yourdomain.com",
    "subject": "Welcome!",
    "createdAt": "2026-07-15T10:30:00.000Z"
  },
  "message": "Email queued for delivery"
}

GET /v1/emails/:id

Returns a single email you own, including delivery status and engagement counts.

GET /v1/emails/:id
curl https://api.sendridge.com/v1/emails/665f1c2e9b1d2a0012345678 \
  -H "Authorization: Bearer $SENDRIDGE_API_KEY"
200 OK
{
  "data": {
    "_id": "665f1c2e9b1d2a0012345678",
    "to": ["customer@example.com"],
    "from": "you@yourdomain.com",
    "subject": "Welcome!",
    "status": "delivered",
    "openCount": 2,
    "clickCount": 1,
    "createdAt": "2026-07-15T10:30:00.000Z",
    "updatedAt": "2026-07-15T10:30:04.000Z"
  }
}

GET /v1/emails

Paginated list of your emails, newest first. Query params: page (default 1) and limit (default 20).

GET /v1/emails
curl "https://api.sendridge.com/v1/emails?page=1&limit=20" \
  -H "Authorization: Bearer $SENDRIDGE_API_KEY"

POST /v1/emails/batch

Up to 100 emails in one request, as an array or { emails: [...] }, each shaped like a /send body. Every email is checked first: if any is invalid, none is sent and the 400 lists the problems by index. Each valid email is then sent on its own, so one refused (an unverified domain, suppressed recipients, a rate limit) doesn't stop the rest. Responds 202 with each email's outcome in order, or 422 if none was queued.

202 Accepted
{
  "data": [
    { "index": 0, "id": "665f1c2e9b1d2a0012345678", "status": "queued", "to": ["ada@example.com"], "scheduledAt": null },
    { "index": 1, "error": { "statusCode": 403, "message": "Domain other.com is not verified. Please verify your domain before sending." } }
  ],
  "message": "1 of 2 emails queued for delivery"
}

Scheduling, attachments and sharing

/send and /batch also take scheduledAt (an ISO 8601 date and time with a Z or an offset, up to 30 days ahead; the email waits with status scheduled) and attachments: up to 10 files, 10 MB in all, each { filename, content, contentType? } with content in base64. Executable file types are refused. Files are kept privately, served only to your account, and stored once however many emails send the same file.

MethodPathWhat it does
PATCH/v1/emails/:idReschedule: { scheduledAt }. A time already due sends it now. 409 unless it's scheduled.
POST/v1/emails/:id/cancelCancel a scheduled email; its status becomes canceled.
GET/v1/emails/:id/attachmentsIts files: id, filename, contentType, size, downloadUrl.
GET/v1/emails/:id/attachments/:attachmentIdOne file's details.
GET/v1/emails/:id/attachments/:attachmentId/contentThe file itself, with your API key.
POST/v1/emails/:id/shareA link anyone can open to view the email: { expiresInHours? } (default 168, up to 720). Returns url and expiresAt.
DELETE/v1/emails/:id/shareEvery link shared for the email so far stops working.

Contacts

Your audience, addressed by contact id or email address. API keys need the read permission for GET and write for the rest. Contacts come back as { id, email, firstName, lastName, unsubscribed, tags, topics, createdAt, updatedAt }, where topics lists the topics the contact has a choice about, as { id, subscribed }.

MethodPathWhat it does
POST/v1/contactsCreate, or update the contact with this email. 201 when created, 200 when updated.
GET/v1/contactsNewest first. Query: limit (1–100, default 50), after (the previous page's nextCursor), unsubscribed (true or false), tag, topic (a topic id: contacts who receive it).
GET/v1/contacts/:idOrEmailOne contact.
PATCH/v1/contacts/:idOrEmailChange firstName, lastName, tags, topics or unsubscribed.
DELETE/v1/contacts/:idOrEmailDelete the contact.
POST/v1/contacts/batchUp to 1,000 contacts at once, with a result per row.
POST /v1/contacts
curl -X POST https://api.sendridge.com/v1/contacts \
  -H "Authorization: Bearer $SENDRIDGE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "ada@example.com",
    "firstName": "Ada",
    "tags": ["newsletter"],
    "consentEvidence": "Newsletter form on example.com"
  }'
201 Created
{
  "data": {
    "id": "6ae4aec514de803c3fadc18a",
    "email": "ada@example.com",
    "firstName": "Ada",
    "lastName": null,
    "unsubscribed": false,
    "tags": ["newsletter"],
    "topics": [],
    "createdAt": "2026-10-30T10:00:00.000Z",
    "updatedAt": "2026-10-30T10:00:00.000Z"
  },
  "created": true
}
FieldTypeRequiredDescription
emailstringYesMatched case-insensitively; stored in lower case.
firstName, lastNamestringNoUp to 100 characters each.
unsubscribedbooleanNotrue unsubscribes. false is honoured only for an address that never opted out.
tagsstring[]NoReplaces the contact's tags (lower case, up to 50).
topics{ id, subscribed }[]NoTopic choices to set; topics not listed keep theirs. A topic the person opted out of themselves stays off.
consentEvidencestringNoHow this person agreed to hear from you; recorded with the contact. Up to 500 characters.

POST /v1/contacts/batch

Creates or updates up to 1,000 contacts in one request with the same rules as POST /v1/contacts. Rows that repeat an address are merged into the first; an invalid address is reported for its row instead of failing the batch. Set mergeTags to add tags to each contact's tags instead of replacing them.

Request
{
  "consentEvidence": "Customers who opted in at checkout",
  "mergeTags": true,
  "contacts": [
    { "email": "ada@example.com", "tags": ["vip"] },
    { "email": "not-an-address" },
    { "email": "grace@example.com", "firstName": "Grace" }
  ]
}
200 OK
{
  "data": {
    "created": 1, "updated": 1, "unchanged": 0, "failed": 1, "withheld": 0,
    "rows": [
      { "index": 0, "email": "ada@example.com", "outcome": "updated" },
      { "index": 1, "email": "not-an-address", "outcome": "error", "error": "Not a valid email address" },
      { "index": 2, "email": "grace@example.com", "outcome": "created" }
    ]
  }
}

Topics

Topics are the kinds of email you send, like product news or a weekly digest. Send a broadcast on a topic and only the people who receive it get the email, and its unsubscribe link (including the mail client's one-click Unsubscribe button) removes them from that topic alone. The unsubscribe page lists your public topics, so people can choose what they receive. Up to 20 per account; same permissions as contacts.

MethodPathWhat it does
POST/v1/topicsCreate a topic.
GET/v1/topicsYour topics, oldest first, each with subscriberCount: the subscribed contacts who receive it now.
GET/v1/topics/:idOne topic, with subscriberCount.
PATCH/v1/topics/:idChange any field. A new defaultSubscription changes who receives it now; choices people made are kept.
DELETE/v1/topics/:idDelete it and every contact's choice about it. 409 topic_in_use while a draft broadcast uses it.
FieldTypeRequiredDescription
namestringYesUp to 60 characters, unique in your account.
descriptionstringNoShown under the name on the unsubscribe page. Up to 200 characters.
defaultSubscriptionopt_out | opt_inNoopt_out (the default): every subscribed contact receives it unless they opt out. opt_in: only contacts who opted in.
visibilitypublic | privateNopublic (the default) topics are listed on the unsubscribe page. A private topic's name is never shown; its emails still unsubscribe from it.

Set a contact's choices with the topics field of the contacts API, for example from a checkbox on your signup form. As with unsubscribing, when a person opts out of a topic themselves only they can opt back in: your API calls can't undo it.

Segments

Saved rules that pick contacts, for targeting a broadcast. A segment is evaluated whenever it is used, so it is always current, and only subscribed contacts are ever counted or sent to. Up to 50 per account, with up to 10 conditions each. Responses include contactCount.

MethodPathWhat it does
POST/v1/segmentsSave a segment: { name, description?, match, conditions }, or { name, kind: "manual" } for one you add contacts to.
POST/v1/segments/previewCount rules without saving them: { match, conditions } returns contactCount and the newest ten contacts.
GET/v1/segmentsYour segments, oldest first.
GET/v1/segments/:idOne segment.
GET/v1/segments/:id/contactsIts contacts, newest first. Query: limit, after.
POST/v1/segments/:id/contactsManual segments: add existing contacts, { contacts: [id or email, ...] } (up to 1,000). Returns added and notFound.
GET/v1/contacts/:idOrEmail/segmentsThe segments a contact is in now.
POST/v1/contacts/:idOrEmail/segments/:segmentIdAdd a contact to a manual segment. 409 segment_has_rules for a rules segment.
DELETE/v1/contacts/:idOrEmail/segments/:segmentIdTake a contact out of a manual segment.
GET/v1/segments/:id/metricsSize, growth and broadcast results (see Metrics).
PATCH/v1/segments/:idChange the name, description, match or conditions.
DELETE/v1/segments/:idDelete it (contacts aren't affected). 409 segment_in_use while a draft broadcast targets it.
fieldoperatorvalue
taghas, not_hasA tag.
emailends_with, containsText such as @example.com (case doesn't matter).
createdafter, beforeAn ISO date: when the contact was added.
topicsubscribed, not_subscribedA topic id: whether the contact receives it.
engagementis, is_notPaid plans: a level (active, warm, cooling, cold, never_engaged, new).
validationis, is_notPaid plans: the last address check (valid, risky, invalid, unknown, unchecked).
POST /v1/segments
{
  "name": "Acme VIPs",
  "match": "all",
  "conditions": [
    { "field": "tag", "operator": "has", "value": "vip" },
    { "field": "email", "operator": "ends_with", "value": "@acme.com" }
  ]
}

Engagement and sunsetting

Paid plans. Every contact has a level from when they last opened or clicked one of your emails: active (30 days), warm (90), cooling (180), cold (longer), never_engaged (sent 5 or more broadcasts, never opened or clicked) and new. Contacts from the contacts API carry engagement: the level, a 0–100 score (clicks count in full, opens for 60%, because Apple Mail opens every email), the last open and click, and sunset. Filter GET /v1/contacts with engagement=cold.

Your sunset rule leaves contacts out of broadcasts when they have had no opens or clicks in 3, 6, 9 or 12 months, and optionally when they never opened any of their last 5, 10 or 20 broadcasts. Contacts added during that time, or never sent a broadcast, are never left out. Nobody is deleted, and transactional email isn't affected. A broadcast with audienceFilter.sunset: "only" goes only to the contacts the rule leaves out: put {{stay_subscribed_url}} on its button, and anyone who confirms on that page is active again.

MethodPathWhat it does
GET/v1/engagementThe levels, your rule ({ enabled, months, neverEngagedAfter }), and the count at each level.
GET/v1/engagement/sunsetting/previewHow many contacts months and neverEngagedAfter would leave out now.
PUT/v1/engagement/sunsettingSet the rule: { enabled, months: 3 | 6 | 9 | 12, neverEngagedAfter: 0 | 5 | 10 | 20 }.
POST/v1/engagement/reengagementA draft "Do you still want to hear from us?" broadcast to the contacts the rule leaves out. Needs the key's Broadcasts permission.

Address validation

Paid plans. Whether an address is worth sending to, before it bounces. invalid: bad syntax, no mail server, a bounce or complaint on your account, or a hard bounce on Sendridge in the last year (kept only as a one-way hash, without the address or which account sent to it). risky: a disposable domain, a role address (info@, support@), a likely typo (with a suggestion), or an old bounce. unknown: the domain couldn't be checked just now. Sendridge never contacts the mailbox itself. Each distinct address uses one validation from your month: 5,000 on Starter, 20,000 on Growth, 100,000 on Pro, plus packs of 10,000. Past it, 429 validation_limit.

MethodPathWhat it does
POST/v1/validate{ email } or { emails: [...] } (up to 1,000): status, reasons, suggestion, checks, and the month's usage.
GET/v1/validate/usageUsed, allowance (plan plus packs), remaining and resetsAt.
POST/v1/validate/jobsCheck your contacts in the background: { scope: "subscribed" | "all", onlyUnchecked }. Results are stored on each contact.
GET/v1/validate/jobs/currentThe latest list check: status, processed, total and counts.
POST/v1/validate/jobs/:id/cancelStop a list check.

Contacts carry validation (their last check, or null). Pass validate: true to POST /v1/contacts to refuse an invalid address (422 invalid_address), and validation: { skip: "invalid" | "invalid_and_risky" } to POST /v1/contacts/batch to leave those rows out (outcome: "skipped"). Filter GET /v1/contacts with validation=invalid.

Content check

Paid plans. What in an email is likely to hurt it in the inbox, found before it goes out: spam-trigger wording, shouting, broken or suspicious links, emails that are mostly pictures, Gmail's 102 KB clipping limit, and a missing or thin plain-text version. It sends nothing and uses no allowance. Results are advice. Only a dead unsubscribe link or a damaged footer has level error, and those stop a broadcast on every plan.

MethodPathWhat it does
POST/v1/emails/checkAny email: { subject, html and/or text, previewText?, links? }. Needs the sendEmail permission.
POST/v1/broadcasts/:id/content-checkA draft broadcast as it would be sent, every A/B version included: { links? }. Needs the broadcasts permission.

Both return ready, summary (errors, warnings, notes), issues (each with level, code, category and message), stats, and how many links and pictures were tried (linksChecked, linksSkipped, imagesChecked, imagesSkipped). Links in the plain-text version count too. Each is tried unless you pass links: false, up to 25 links and 15 pictures per check. A site that refuses automated requests comes back as link-unconfirmed, a note rather than a warning. On a designed broadcast, an issue can carry nodeId, the block it's about, and version when that block is in an A/B version's own design.

Broadcasts

One email to many contacts. GET requests need the key's read permission; everything else needs broadcasts. A broadcast is created as a draft, then sent now or scheduled; every check a send makes (audience, sender, postal address, content) runs at that moment either way.

MethodPathWhat it does
POST/v1/broadcastsCreate a draft: { subject, fromEmail, fromName?, replyTo?, name?, previewText?, html? | text? | templateId?, audienceFilter?, abTest? }.
GET/v1/broadcastsNewest first. Query: status (draft, scheduled, sending, testing, sent, failed), search.
GET/v1/broadcasts/:idOne broadcast.
PATCH/v1/broadcasts/:idChange a draft. A scheduled or sent one can only be renamed.
DELETE/v1/broadcasts/:idDelete it.
POST/v1/broadcasts/:id/duplicateA new draft with the same content and audience.
POST/v1/broadcasts/:id/testSend yourself a copy: { email, variant? } (an A/B version; A by default).
POST/v1/broadcasts/:id/sendSend now, or { scheduledAt } (up to 30 days ahead). 429 monthly_limit if it's bigger than the emails left that month.
POST/v1/broadcasts/:id/cancelCancel a scheduled broadcast (it becomes a draft again), or stop a running A/B test.
GET/v1/broadcasts/:id/ab-testAn A/B test's versions with recipients, opens and clicks, who is ahead, and the winner. Paid plans.
GET/v1/broadcasts/:id/ab-test/versions/:variantOne version of a sent A/B test as it went out: subject, from and html, with sample personalisation.
POST/v1/broadcasts/:id/ab-test/winnerPick the winner now: { variant: "A" | "B" | "C" | "D" }. It goes to everyone who wasn't in the test.
GET/v1/broadcasts/:id/recipientsWho it went to, with each delivery status, opened and clicked. Query: limit, after, status.
GET/v1/broadcasts/:id/linksLinks that were clicked: url, clicks, uniqueClicks.
GET/v1/broadcasts/:id/metricsSent, delivered, opened, clicked, bounced and complained, with rates.
POST/v1/broadcasts/audience/countHow many contacts an audienceFilter reaches now.

audienceFilter is { mode: "all" | "tag" | "segment", tag?, segmentId?, topicId? }; with a topicId, only the topic's receivers get it and its unsubscribe links unsubscribe from that topic. Content can use {{contact.first_name|there}} and the other personalisation tokens; the unsubscribe link and your postal address are added to every email.

abTest (paid plans) is { enabled, variants: [{ subject?, previewText?, fromName?, html?, text?, editorState? }], testPercent?, winnerMetric?, waitHours? }. Versions B to D change what they name; empty fields keep version A's, which is the broadcast itself. A version of a broadcast made from html can have its own html and text; one designed in the dashboard can have its own design. testPercent (10–50, default 20) of the audience is split evenly at random. After waitHours (1–48, default 4), the version with the most unique clicks (the default) or opens goes to everyone else. With manual, you pick it. While the test runs, the broadcast's status is testing. On the Free plan, sending one returns 403 plan_required.

POST /v1/broadcasts
{
  "subject": "October news",
  "fromEmail": "news@yourdomain.com",
  "fromName": "Acme",
  "html": "<p>Hi {{contact.first_name|there}}</p>",
  "audienceFilter": { "mode": "segment", "segmentId": "6ae4aec514de803c3fadc18a" }
}

Templates

Saved broadcast designs (editor documents). Each has a working copy, which edits change, and a published version, which POST /v1/broadcasts with a templateId uses. Responses include hasUnpublishedChanges. Up to 200 per account.

MethodPathWhat it does
POST/v1/broadcast-templatesSave one: { name, document, category?, tags? }.
GET/v1/broadcast-templatesMost recently changed first.
GET/v1/broadcast-templates/:idOne template.
PATCH/v1/broadcast-templates/:idChange the working copy. With baseVersion, a save based on an older version is refused (409).
POST/v1/broadcast-templates/:id/publishPublish the working copy.
POST/v1/broadcast-templates/:id/duplicateA copy.
DELETE/v1/broadcast-templates/:idDelete it; broadcasts made from it keep their content.

Metrics

GET /v1/analytics/metrics?from=&to= returns totals, rates and a daily series (UTC days) for your emails over a period: the last 30 days by default, or from=all for everything since your account was created. Each email counts once, by its final status. The same period works on /v1/analytics/broadcasts, /links (the 50 most clicked) and /domains. The Free plan reaches back 30 days: a longer period is shortened, with window.limited set, and one wholly older is refused with 403 plan_required. Paid plans see all history. GET /v1/segments/:id/metrics gives a segment's size, how many joined in the period, and how the broadcasts sent to it did. Both need analytics on your plan.

GET /v1/analytics/metrics
{
  "data": {
    "from": "2026-10-01T00:00:00.000Z", "to": "2026-10-31T00:00:00.000Z",
    "requested": 1200, "sent": 1180, "delivered": 1162, "opened": 540, "clicked": 131,
    "bounced": 18, "complained": 1, "failed": 4, "suppressed": 16, "queued": 0,
    "rates": { "delivery": 0.9847, "open": 0.4647, "click": 0.1127, "bounce": 0.0153, "complaint": 0.0009 },
    "daily": [{ "date": "2026-10-01", "requested": 40, "sent": 39, "delivered": 39, "opened": 18, "clicked": 4, "bounced": 0, "complained": 0, "failed": 0, "suppressed": 1, "queued": 0 }]
  }
}

Webhooks

Sendridge sends a POST with a JSON body to each of your endpoints that subscribes to an event. The body's data is the contact in the same shape the contacts API returns.

EventWhen
contact.createdA contact was added (API, import, dashboard).
contact.updatedIts name, tags or topic choices changed, or the person subscribed again from their own link.
contact.unsubscribedIt unsubscribed. data.reason: link, one-click, api, import or dashboard.
contact.suppressedIts address bounced hard or it complained: Sendridge won't send to it. data.reason: bounce or complaint.
contact.deletedIt was deleted. data is its last state.
webhook.testSent by Send test in the dashboard or POST /v1/webhooks/:id/test.
contact.unsubscribed
{
  "id": "evt_6ae4af569efa59d6f0bb190d",
  "type": "contact.unsubscribed",
  "createdAt": "2026-10-30T10:00:00.000Z",
  "data": {
    "id": "6ae4aec514de803c3fadc18a",
    "email": "ada@example.com",
    "firstName": "Ada",
    "lastName": null,
    "unsubscribed": true,
    "tags": ["newsletter"],
    "topics": [],
    "createdAt": "2026-10-29T09:12:00.000Z",
    "updatedAt": "2026-10-30T10:00:00.000Z",
    "reason": "link"
  }
}

Requests are signed in the Standard Webhooks format, so libraries for most languages can verify them. Three headers come with each request:

HeaderValue
webhook-idThe event id. The same on every retry: use it to skip events you have handled.
webhook-timestampUnix seconds when this attempt was signed. Reject requests more than five minutes old.
webhook-signaturev1, followed by base64(HMAC-SHA256(secret, webhook-id + "." + webhook-timestamp + "." + raw body)). The secret is the base64 after whsec_. Several may be listed, separated by spaces.

Answer with any 2xx within ten seconds. Anything else, or no answer, is retried with the same id and body after 30 seconds, 2 and 10 minutes, then 1, 3, 6, 12 and 24 hours, about two days in all. An endpoint that fails for five days is switched off, with the reason shown in the dashboard. Two events from one change may arrive in either order: use createdAt when order matters. Endpoint URLs must use https and a public address. Webhooks are included in the Starter plan and above: 3 endpoints on Starter, 5 on Growth and 20 on Pro. Adding one past your plan's number returns 403 plan_required; GET /v1/webhooks returns limit with used and max.

Webhook endpoints

Manage endpoints in the dashboard under Developer tools › Webhooks, or with an API key that has the webhooks permission. Up to 10 per account.

MethodPathWhat it does
POST/v1/webhooksAdd an endpoint: { url, events, description? }. The response includes its secret.
GET/v1/webhooksYour endpoints (without secrets).
GET/v1/webhooks/:idOne endpoint.
PATCH/v1/webhooks/:idChange url, events, description, or enabled (switching it on again clears the failure state).
DELETE/v1/webhooks/:idDelete it and its delivery log.
GET/v1/webhooks/:id/secretThe signing secret.
POST/v1/webhooks/:id/secret/rotateA new secret, effective immediately.
POST/v1/webhooks/:id/testSend a webhook.test event now; returns the delivery and your endpoint's answer.
GET/v1/webhooks/:id/deliveriesThe delivery log, newest first, kept 30 days. Query: limit, after, status (pending, succeeded, failed).
POST/v1/webhooks/:id/deliveries/:deliveryId/retrySend a delivery again now.

REST API — Errors

StatusMeaningTypical causes
400Validation errorMissing/invalid fields; details lists per-field errors
401UnauthorizedMissing, invalid, revoked, or expired API key
403ForbiddenUnverified sending domain, key permissions, IP allowlist, plan restrictions
403 sandbox_restrictedAccount is not liveA send to another recipient is blocked; test sends to your registered address still work. Request live sending in the dashboard.
403 domain_not_approvedDomain is not approvedA live account sent to another recipient from an unapproved domain. Request approval on the Domains page.
403 plan_requiredNot in your planThe feature (for example webhooks) isn't included in your plan, or you're using every webhook endpoint it includes.
403 domain_over_limitDomain past your limitThe sending domain is past the number your plan and extra-domain add-ons include (an add-on ended, or the plan changed). Renew, upgrade, or remove a domain.
404Not foundUnknown email id, contact or webhook endpoint
409 resubscribe_blockedCan't resubscribeThe contact unsubscribed (from everything or from that topic) or its address is suppressed; only the person can subscribe again.
409 topic_in_use, segment_in_useIn useA draft or scheduled broadcast uses the topic or segment; give it another one before deleting it.
409 segment_has_rulesNot a manual segmentContacts join a rules segment by matching it; only a manual segment takes contacts by hand.
409ConflictRescheduling or canceling an email or broadcast that isn't scheduled; editing a sent broadcast.
413Too largeAttachments over 10 MB in all.
503 attachments_unavailableCouldn't store attachmentsFile storage is briefly unavailable; nothing was sent. Try again in a minute.
429Too many requestsPer-minute/hour rate limit or monthly quota exceeded
5xxServer errorSendridge-side problem — safe to retry idempotent requests
Example error
{
  "error": "Validation Error",
  "message": "Invalid request data",
  "details": { "from": ["Invalid email"] }
}

When a response has a code, it identifies the reason and message tells you how to resolve it. The SDK exposes it as err.code: the 403 responses arrive as a PermissionError and resubscribe_blocked as a ConflictError.

Rate limits

Sending limits depend on your plan. The per-minute and per-hour limits count each address and apply across all your API keys; individual keys can carry an extra per-minute cap set in the dashboard. Your allowance of emails covers API emails and broadcasts together, starts again every 30 days on a paid plan or on the 1st on Free, and anything scheduled is set aside from it. When you hit a limit the API returns 429 with a message describing which limit was exceeded; running out of the allowance carries the code monthly_limit. A broadcast to more contacts than your plan allows at one go is refused with 403 and contact_limit.

Plan limits are listed on the pricing page.

Questions? Open a ticket from your dashboard, or start with the free plan.