Node.js

The quickest way to send email from Node.js is the official SDK, @xem.email/sdk. For anything the SDK does not cover yet, such as analytics, call the API directly with fetch. Both need an API key. Create one in Settings → API keys and keep it in an environment variable, never in code.

Install

npm install @xem.email/sdk

Send an email

import { Xem } from "@xem.email/sdk";

const xem = new Xem({ apiKey: process.env.XEM_API_KEY });

const result = await xem.email.send({
  to: "reader@example.com",
  subject: "Welcome to the newsletter",
  html: "<p>Thanks for signing up.</p>",
});

console.log(result); // { status: "Email saved to outbox", id: "…" }

Xem queues the email in your workspace outbox and sends it through your default sender.

Send a saved template

await xem.email.send({
  to: "reader@example.com",
  subject: "Your weekly digest",
  templateId: process.env.DIGEST_TEMPLATE_ID,
  data: [{ first_name: "Ada" }],
});

Schedule, reply-to and test sends

await xem.email.send({
  to: "reader@example.com",
  subject: "Reminder",
  html: "<p>The webinar starts tomorrow.</p>",
  scheduleAt: "2026-11-02T09:00:00Z",
  replyTo: "hello@yourdomain.com",
  test: true,
});

Self-hosted installs

Point the SDK at your own API:

const xem = new Xem({
  apiKey: process.env.XEM_API_KEY,
  baseUrl: "https://api.example.com/api/v1",
});

Call the API with fetch

Every endpoint accepts the API key in the X-API-Key header. This example sends an email with a requestId, so a retry after a network error cannot send it twice:

import { randomUUID } from "node:crypto";

const API = process.env.XEM_API_URL ?? "https://api.xem.email/api/v1";

async function xem(path: string, init: RequestInit = {}) {
  const res = await fetch(`${API}${path}`, {
    ...init,
    headers: {
      "X-API-Key": process.env.XEM_API_KEY!,
      "Content-Type": "application/json",
      ...init.headers,
    },
  });
  if (!res.ok) throw new Error(`Xem API ${res.status}: ${await res.text()}`);
  return res.json();
}

const requestId = randomUUID();
await xem("/emails", {
  method: "POST",
  body: JSON.stringify({
    to: "reader@example.com",
    subject: "Your receipt",
    html: "<p>Thanks for your order.</p>",
    data: {},
    requestId,
  }),
});

Reusing a requestId for a different message returns 409.

Read campaign analytics

const stats = await xem(`/analytics/campaign?campaignId=${campaignId}`);

See the API reference for the full list of endpoints and response fields.

Handle errors

Status	Meaning	What to do
`400`	The request is invalid, or the chosen sender is unavailable	Check the fields and that a sender is active
`401`	The API key is missing or invalid	Check the `X-API-Key` header
`404`	The template does not exist	Check `templateId`
`409`	The `requestId` was used for a different message	Generate a new UUID
`429`	Too many requests	Wait and retry with backoff

See Error handling and Rate limiting for details.

Tutorials

Technical

Examples