Documentation

Getting started

sendthen is a single Next.js app backed by one SQLite file. Run it locally with pnpm, or in production with Docker:

# local
pnpm install
cp .env.example .env.local   # set ADMIN_PASSWORD
pnpm dev

# production
docker build -t sendthen .
docker run -p 3000:3000 -v sendthen-data:/data -e ADMIN_PASSWORD=... sendthen

Open the dashboard and create the first account — it becomes the instance admin (set DISABLE_SIGNUP=true afterwards to block public registration). Create an API key under API Keys, then send:

curl -X POST http://localhost:3000/api/v1/emails \
  -H "Authorization: Bearer st_..." \
  -H "Content-Type: application/json" \
  -d '{
    "from": "you <hello@yourdomain.com>",
    "to": "user@example.com",
    "subject": "Hello",
    "html": "<strong>It just sends.</strong>"
  }'

In the default sandbox mode the email is DKIM-signed, captured to disk, and marked delivered — the entire pipeline (queue → send → events → webhooks) runs without touching the network.

Authentication

Every API request needs a bearer token. Keys start with st_, are shown once at creation, and are stored as SHA-256 hashes.

Authorization: Bearer st_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Mail modes & providers

The instance default transport is SENDTHEN_MAIL_MODE; every user can override it in Settings with their own SES credentials or SMTP relay:

Outside sandbox mode, only verified domains may send. Locally you can set SENDTHEN_DNS_MOCK=verified to make every DNS check pass.

Amazon SES bounce feedback

Point an SNS topic (bounces + complaints) at POST /api/ses/feedback. Subscription confirmation is automatic; hard bounces and complaints update email status and auto-populate your suppression list.

Emails API

{ "id": "em_4kq0w2xr..." }

Templates

Store reusable emails with {{variables}} in subject and body, then send by id. The dashboard includes a no-code visual builder (Templates → Open builder): compose from blocks — logo, headings, buttons, images, columns, OTP code, social links, footer with unsubscribe — and it compiles to table-based, inline-styled, email-client-safe HTML. Built templates stay re-editable.

POST /api/v1/templates        { "name": "welcome", "subject": "Hi {{name}}", "html": "<h1>Hey {{name}}</h1>" }
GET  /api/v1/templates        list
GET/PATCH/DELETE /api/v1/templates/:id

POST /api/v1/emails           { "from": "...", "to": "...", "template_id": "tpl_...", "variables": { "name": "Ada" } }

Unknown variables are left as-is; explicit html/text/subject in the send call win over the template.

Audiences & broadcasts

Audiences hold contacts; broadcasts fan out one personalized email per subscribed contact with {{first_name}} {{last_name}} {{email}} {{unsubscribe_url}} substitution and RFC 8058 one-click unsubscribe headers.

POST /api/v1/audiences                  { "name": "newsletter" }
POST /api/v1/audiences/:id/contacts     { "email": "a@b.com", "first_name": "Ada" }
GET  /api/v1/audiences/:id/contacts     list

POST /api/v1/broadcasts                 { "audience_id": "aud_...", "from": "...", "subject": "Hey {{first_name}}", "html": "..." }
POST /api/v1/broadcasts/:id/send        → { "queued": 120, "skipped": 3 }

Unsubscribed and suppressed contacts are skipped automatically. Unsubscribe links are HMAC-signed and work without login.

Open & click tracking

Enable per-account in Settings or per-send with track_opens / track_clicks. Requires SENDTHEN_PUBLIC_URL. Opens use a signed 1×1 pixel; clicks rewrite links through a signed redirect. Both emit email.opened / email.clicked events to your webhooks and show up in Overview analytics.

Suppressions

Addresses on your suppression list never receive email: they are dropped at send time, and an email whose every recipient is suppressed fails with recipients_suppressed. Hard bounces and complaints (via SES feedback) are added automatically; manual entries via the dashboard.

Domains API

Adding a domain generates a 2048-bit DKIM keypair and returns the DNS records to publish:

POST /api/v1/domains          { "name": "mail.yourdomain.com" }
GET  /api/v1/domains          list
GET  /api/v1/domains/:id      detail incl. records[]
POST /api/v1/domains/:id/verify   re-check DNS
DELETE /api/v1/domains/:id    remove

status becomes verified once both records resolve. Verification also runs from the dashboard with one click.

API Keys & scopes

POST   /api/v1/api-keys      { "name": "production", "scopes": ["emails.send", "emails.read"] }
GET    /api/v1/api-keys      list (prefixes + scopes)
DELETE /api/v1/api-keys/:id  revoke

The full token is returned only once, in the create response. Omit scopesfor full access. A request outside a key's scopes fails with 403 missing_scope.

Inbound email

sendthen can receive mail for your verified domains and show it under Emails → Receiving, with one-click forwarding through your configured transport. Three ways in:

curl -X POST https://send.yourdomain.com/api/inbound/raw \
  -H "Authorization: Bearer <ingest key>" \
  --data-binary @message.eml

Receiving when inbound port 25 is blocked

Most cloud hosts (Hetzner, AWS, GCP, …) drop inbound connections on port 25, so pointing MX straight at the instance often can't work — the SMTP handshake never reaches the server. Route mail through Cloudflare Email Routing instead: Cloudflare accepts the SMTP on its own infrastructure and an Email Worker forwards the raw message to the HTTP ingest above. No open port on your server.

export default {
  async email(message, env) {
    const raw = await new Response(message.raw).arrayBuffer();
    const url =
      "https://send.yourdomain.com/api/inbound/raw?to=" +
      encodeURIComponent(message.to);
    await fetch(url, {
      method: "POST",
      headers: {
        authorization: "Bearer " + env.INGEST_KEY,
        "content-type": "message/rfc822",
      },
      body: raw,
    });
  },
};

The recipient domain must match a domain registered in sendthen so the message is stored against the right team. Only the MX changes — outbound sending (DKIM / stmail._domainkey) is unaffected, and DMARC still passes via DKIM alignment.

Verifying receiving

A domain's detail page has a Verify receivingcheck — it resolves the domain's MX and confirms it points at this instance, for the built-in SMTP route — and a Test receiving panel that surfaces the most recent inbound message for the domain. With the SES or Cloudflare relay routes the MX points at the provider, so confirm delivery via Test receiving or Emails → Receiving rather than the MX check.

Webhooks

Subscribe to lifecycle events. Deliveries are retried 5× with backoff (5s → 5m → 30m → 2h) and logged in the dashboard.

POST /api/v1/webhooks   { "url": "https://you.com/hooks", "events": ["email.delivered"] }

Payload

{
  "type": "email.delivered",
  "created_at": "2026-07-02T09:31:04.220Z",
  "data": {
    "email_id": "em_4kq0w2xr...",
    "from": "you <hello@yourdomain.com>",
    "to": ["user@example.com"],
    "subject": "Hello",
    "message_id": "<...>"
  }
}

Verifying signatures

Headers are svix-compatible: webhook-id, webhook-timestamp, webhook-signature. The signed content is `${id}.${timestamp}.${body}`, HMAC-SHA256 with your endpoint's whsec_ secret:

import { createHmac, timingSafeEqual } from "node:crypto";

function verify(req: Request, rawBody: string, secret: string) {
  const id = req.headers.get("webhook-id")!;
  const ts = req.headers.get("webhook-timestamp")!;
  const sig = req.headers.get("webhook-signature")!;

  const mac = createHmac("sha256", Buffer.from(secret.replace(/^whsec_/, "")))
    .update(`${id}.${ts}.${rawBody}`)
    .digest("base64");

  const expected = Buffer.from(`v1,${mac}`);
  const received = Buffer.from(sig);
  return (
    expected.length === received.length &&
    timingSafeEqual(expected, received)
  );
}

SDK reference

The TypeScript SDK ships as the sendthen npm package (npm install sendthen) — zero dependencies, works in Node 18+, Bun, Deno, and edge runtimes (anything with fetch). The package also includes a CLI: npx sendthen login.

Constructor

import { SendThen } from "sendthen";

const st = new SendThen("st_xxxxxxxx", {
  baseUrl: "https://send.yourdomain.com", // default: SENDTHEN_BASE_URL env or http://localhost:3000
  fetch: customFetch,                     // optional fetch override
});

Every method returns a promise. Non-2xx responses throw SendThenError with statusCode, name, and message.

st.emails

const { id } = await st.emails.send(
  {
    from: "you <hello@yourdomain.com>",
    to: ["user@example.com"],
    subject: "Welcome aboard",
    html: "<strong>It just sends.</strong>",
    scheduled_at: "2026-07-03T09:00:00+03:00", // optional
  },
  { idempotencyKey: "welcome-user-42" },       // optional, retry-safe
);

const email = await st.emails.get(id);
console.log(email.status); // queued → sent → delivered

st.domains

const domain = await st.domains.create("mail.yourdomain.com");
// publish domain.records, then:
const verified = await st.domains.verify(domain.id);
console.log(verified.status); // "verified"

st.apiKeys

st.webhooks

const hook = await st.webhooks.create(
  "https://you.com/hooks/sendthen",
  ["email.delivered", "email.bounced"],
);
// store hook.secret for signature verification

Errors

All errors share one JSON shape:

{ "statusCode": 422, "name": "validation_error", "message": "Either html or text must be provided." }