Use the API.

1Before you start

The API lives on your own install, at your own web address. Everything here talks to your Newsletter Sender, not to us. In the examples, swap news.yourdomain.com for your install's address.

1. Open Settings, then API. In your Newsletter Sender, click Settings then API. Your API address is at the top, with a copy button. It looks like https://news.yourdomain.com/api/v1.
2. Make a key. Click Make a key and give it a name you'll recognise later, such as Website sign up form. Each key belongs to one brand.
3. Copy the key straight away. It starts ns_live_ and is shown once only. Keep it somewhere safe, such as your password manager or your server's secrets. You can have up to 10 keys for each brand, and you can delete one at any time.

2Keys, limits and errors

Send your key in a header with every request. Either of these works:

Authorization: Bearer ns_live_...
X-API-Key: ns_live_...

A key in the web address, such as ?key=ns_live_..., is refused. Web addresses end up in logs and browser history, so if you've ever sent a key that way, delete it and make a new one.

To check your key works, ask which brand it belongs to:

curl https://news.yourdomain.com/api/v1/me \
  -H "Authorization: Bearer ns_live_..."

{ "brand": { "id": "...", "name": "Weekly Notes" }, "docs": "https://newslettersender.com/help/api/" }

3Add a subscriber

This is the one most people need: someone fills in a form on your website and you add them to a list.

curl https://news.yourdomain.com/api/v1/subscribers \
  -H "Authorization: Bearer ns_live_..." \
  -H "Content-Type: application/json" \
  -d '{"email":"sam@example.com","name":"Sam","list":"weekly","tags":["spring-offer"]}'

{
  "id": "3f9c2a7b81d04e6a",
  "email": "sam@example.com",
  "name": "Sam",
  "fields": {},
  "tags": ["spring-offer"],
  "status": "pending_confirmation",
  "lists": [
    { "id": "...", "slug": "weekly", "name": "Weekly", "status": "pending_confirmation",
      "joined_at": "2026-11-06T09:30:00.000Z", "confirmed_at": null, "left_at": null }
  ],
  "created_at": "2026-11-06T09:30:00.000Z",
  "result": "pending_confirmation"
}

The result tells you what happened:

4Find, change and remove subscribers

Wherever you see {id or email}, you can use the subscriber's id or their email address.

curl -X PATCH https://news.yourdomain.com/api/v1/subscribers/sam@example.com \
  -H "Authorization: Bearer ns_live_..." \
  -H "Content-Type: application/json" \
  -d '{"fields":{"city":"Leeds"},"add_tags":["customer"]}'

5Lists

GET /api/v1/lists gives you every list in the brand, with its id, slug, name, description, whether it uses double opt in and how many active subscribers it has. Use the slug or id wherever a request asks for a list.

6Campaigns

The API can draft a campaign, but it never sends one. You check it and press send in the app, so nothing goes out to your whole list by mistake.

curl https://news.yourdomain.com/api/v1/campaigns \
  -H "Authorization: Bearer ns_live_..." \
  -H "Content-Type: application/json" \
  -d '{"subject":"Spring news","list":"weekly","html":"<p>Hello</p>"}'

{ "id": "...", "status": "draft", "edit_url": "https://news.yourdomain.com/#email/...", "audience": 1240 }

7Send a one off email

For a single email to one person, such as a receipt or a password reset. It goes from your brand's From name and address, through the same sending service as your newsletters.

curl https://news.yourdomain.com/api/v1/emails \
  -H "Authorization: Bearer ns_live_..." \
  -H "Content-Type: application/json" \
  -d '{"to":"sam@example.com","subject":"Your receipt","text":"Thanks for your order."}'

{ "sent": true, "message_id": "..." }

Send to, subject and html or text (or both), and optionally reply_to. You get 202 once it's handed to your sending service. Addresses that have bounced or complained are refused, to protect your sending reputation.

8Webhooks

A webhook tells your own system the moment something happens, such as a new subscriber, so you don't have to keep asking.

1. Add a webhook. In Settings, API, Webhooks, enter your https address and tick the events you want. You can have up to 5 for each brand.
2. Copy the signing secret. It starts whsec_ and is shown once only. You use it to check each message really came from your Newsletter Sender.
3. Send a test. Click Send a test. Your address gets an event called test.

Each one arrives as a POST with a JSON body like this:

{
  "id": "...",
  "event": "subscriber.subscribed",
  "created_at": "2026-11-06T09:31:00.000Z",
  "data": {
    "subscriber": { "id": "3f9c2a7b81d04e6a", "email": "sam@example.com", "name": "Sam" },
    "campaign_id": null,
    "detail": "Weekly",
    "at": "2026-11-06T09:31:00.000Z"
  }
}

Campaign events have campaign_id, detail and at in data. Three headers come with it: NewsletterSender-Event (the event), NewsletterSender-Delivery (the id) and NewsletterSender-Signature.

9Check the signature

The signature header looks like t=1762421460,v1=5d41.... t is when it was sent, in seconds, and v1 is an HMAC SHA256 of the time, a full stop and the raw body, made with your signing secret. Check it before you trust the message, and turn away anything more than 5 minutes old. In Node:

import crypto from "node:crypto";

// raw is the body exactly as it arrived, before you parse the JSON.
function verify(raw, header, secret) {
  const { t, v1 } = Object.fromEntries(header.split(",").map((p) => p.split("=")));
  const now = Date.now() / 1000;
  if (!t || !v1 || Number(t) + 300 < now || Number(t) > now + 300) return false;
  const want = crypto.createHmac("sha256", secret).update(`${t}.${raw}`).digest("hex");
  return want.length === v1.length && crypto.timingSafeEqual(Buffer.from(want), Buffer.from(v1));
}

10If something goes wrong

Every error comes with a plain English error message saying what to fix. These are the status codes you might see:

Still stuck? Get in touch. Please never send your keys.