Newsletter API: from contact to segment, draft, test and send, in runnable code

A topic holds what someone agreed to receive (“Product updates”) and each contact’s yes or no. A segment is who one campaign goes to: a filter over contacts, worked out again at send time. A broadcast is the campaign. A topic’s default and a segment’s filter can never be edited; a wrong one is replaced by creating a new one.

Set a newsletter topic’s default_subscription to opt_out. The name reads backwards: it means “not subscribed until they say yes”, so a customer who never ticked the box gets nothing. opt_in would mail everyone who has not left.

• A campaign that runs out of quota stops partway. Each recipient is one email from the plan’s single allowance, the same one your receipts use. When it runs out, those already sent stay sent, the campaign is marked failed, and it cannot be resumed. On Free that line is 100 a day (3,000 a month, 900 contacts; 300 a month until the account has a card on file), so a Free campaign to more people stops on the first day, and your receipts, drawn from the same allowance, are refused until the next; the pricing page has the paid allowances. The send script below checks headroom first.
• Nothing tells you a campaign finished. There is no campaign-level webhook. Poll the broadcast’s status, or listen to the per-email webhook events (email.delivered, email.complained), which fire for campaign mail as for any other; the webhooks post shows how to verify their signatures.
• One-click unsubscribe leaves every campaign, not one topic. Every campaign carries the RFC 8058 headers (the one-click guide shows them), and a click there unsubscribes the person from all campaigns; receipts still reach them. To let people leave one topic instead, link {{{PREFERENCES_URL}}} in the body and add your postal address there yourself, because the footer that carries the address is only appended to a body with no unsubscribe link of its own. The link lives on our share host and cannot move to your domain; the same link already sits in every campaign’s List-Unsubscribe header, so the body link adds no new domain to your mail.

Two smaller gaps: a draft can store subject_variants but nothing sends an A/B test yet, and segment filters cannot test opens or clicks, so engagement has to be written to a contact property from webhook events first. If your newsletter depends on subject-line tests or segments built on who opened, Rasket is not the right tool for it yet.

The scripts need Node 22 or later and no packages, and each output below is from running them on 2026-10-17. Each reads the key from RASKET_API_KEY and the base URL from RASKET_API_URL (default https://api.rasket.com). The helper retries only what is safe to repeat: a rate-limit refusal, which carries retry-after, and a failed GET; the rate-limits post explains the limit.

// rasket.mjs: one helper the other scripts import. Node 22+, no packages.
const API = process.env.RASKET_API_URL ?? "https://api.rasket.com";
const KEY = process.env.RASKET_API_KEY;
const sleep = (seconds) => new Promise((r) => setTimeout(r, seconds * 1000));

export async function api(method, path, body, headers = {}) {
  for (let attempt = 1; ; attempt++) {
    const last = attempt === 4;
    let res;
    try {
      res = await fetch(API + path, {
        method,
        headers: {
          Authorization: `Bearer ${KEY}`,
          "Content-Type": "application/json",
          "User-Agent": "acme-newsletter/1.0",
          ...headers,
        },
        body: body === undefined ? undefined : JSON.stringify(body),
      });
    } catch (error) {
      // A network error on a GET is safe to repeat. A POST may have landed.
      if (method === "GET" && !last) {
        await sleep(attempt);
        continue;
      }
      throw error;
    }
    // The rate limit's 429 did nothing and says when to come back. A quota 429
    // has no retry-after, because waiting a second will not fix it.
        // Rasket sends whole seconds; a date or anything else is not retried.
    const retryAfter = Number(res.headers.get("retry-after") ?? NaN);
    if (res.status === 429 && Number.isFinite(retryAfter) && !last) {
      await sleep(retryAfter);
      continue;
    }
    if (res.status >= 500 && method === "GET" && !last) {
      await sleep(attempt);
      continue;
    }
    const text = await res.text();
    let data;
    try {
      data = JSON.parse(text);
    } catch {
      data = { message: text.slice(0, 200) };
    }
    if (!res.ok) {
      const message = `${method} ${path} → ${res.status} ${data.name ?? "error"}: ${data.message}`;
      throw Object.assign(new Error(message), { status: res.status });
    }
    return data;
  }
}

// postal.mjs: once per team. Every campaign footer prints the name and address.
import { api } from "./rasket.mjs";

const team = await api("PATCH", "/team", {
  sender_name: "Acme",
  postal_address: {
    line1: "1 Example Street",
    city: "Springfield",
    postal_code: "12345",
    country: "US",
  },
});
console.log(team.sender_identity);

// draft.mjs: contact → segment → campaign draft → test. Safe to run twice.
import { api } from "./rasket.mjs";

const FROM = process.env.RASKET_FROM ?? "Acme <digest@news.acme.example>";
const TEST_TO = process.env.RASKET_TEST_TO ?? "you@acme.example";
const month = new Date().toISOString().slice(0, 7); // e.g. "2026-10"

// 1. The topic people subscribe to. Created once, then found by name.
const topics = await api("GET", "/topics?limit=100");
const topic =
  topics.data.find((t) => t.name === "Product updates") ??
  (await api("POST", "/topics", {
    name: "Product updates",
    description: "What shipped, once a month.",
    default_subscription: "opt_out", // nobody gets it until they say yes
    visibility: "public",
  }));

// 2. A contact and their opt-in, sent only when the contact is new: a topics entry
//    overwrites their answer, so repeating it would re-subscribe someone who left.
const email = "sam.reader@example.com";
const known = await api("GET", `/contacts/${encodeURIComponent(email)}`).catch((error) => {
  if (error.status === 404) return null;
  throw error;
});
const contact =
  known ??
  (await api("POST", "/contacts", {
    email,
    first_name: "Sam",
    topics: [{ id: topic.id, subscription: "opt_in" }],
  }));

// 3. The audience: everyone opted in to the topic. Also found by name.
const segments = await api("GET", "/segments?limit=100");
const segment =
  segments.data.find((s) => s.name === "Product updates: opted in") ??
  (await api("POST", "/segments", {
    name: "Product updates: opted in",
    filter: { all: [{ topic: topic.id, subscription: "opt_in" }] },
  }));

// 4. This month's campaign, as a draft. Found by name in any status, so a rerun
//    reuses the draft, and stops once this month's campaign has gone out.
const name = `Product update ${month}`;
const found = await api("GET", `/broadcasts?search=${encodeURIComponent(name)}`);
const existing = found.data.find((b) => b.name === name);
if (existing !== undefined && existing.status !== "draft") {
  console.log({ broadcast: existing.id, status: existing.status });
  process.exit(0);
}
const broadcast =
  existing ??
  (await api("POST", "/broadcasts", {
    name,
    segment_id: segment.id,
    topic_id: topic.id,
    from: FROM,
    subject: "What shipped this month",
    preview_text: "Three changes, two minutes to read.",
    // No unsubscribe link of our own: the footer adds one, with the postal address.
    html: `<p>Hi {{{FIRST_NAME|there}}},</p>
<p>Three things shipped this month.</p>`,
  }));

// 5. A test to one inbox. The same key within 24 hours means it is not sent twice.
const test = await api(
  "POST",
  `/broadcasts/${broadcast.id}/test`,
  { to: [TEST_TO] },
  { "Idempotency-Key": `test-${broadcast.id}` },
);

console.log({ contact: contact.id, segment: segment.id, broadcast: broadcast.id, test: test.data });

$ node draft.mjs
{
  contact: '01a14b8c-f8bb-790b-aa22-ef60825a753c',
  segment: '01a14b8c-f925-7e70-8755-0a5ae9e14ff7',
  broadcast: '01a14be7-346d-7cd6-a9b5-104b24f2057f',
  test: [
    {
      id: '01a14be7-349a-7b31-b775-19ddc736f927',
      to: 'you@acme.example'
    }
  ]
}

// send.mjs <broadcast id> [scheduled_at] [--send]: check audience, gates and headroom.
// Without --send it stops after the checks, so what it prints is what the approver reads.
import { api } from "./rasket.mjs";

const args = process.argv.slice(2);
const go = args.includes("--send");
const [id, scheduledAt] = args.filter((arg) => arg !== "--send");

const draft = await api("GET", `/broadcasts/${id}`);
const audience = await api("GET", `/segments/${draft.segment_id}/metrics`);
console.log({ from: draft.from, subject: draft.subject, contacts: audience.subscribed });

// The compliance gate: domain, postal address, segment, account state, body.
const gate = await api("GET", `/broadcasts/${id}/checklist`);
const problems = gate.conditions.filter((c) => !c.passed);

// The content checks: links, merge variables, subject, alt text, unsubscribe link.
const checks = await api("POST", `/broadcasts/${id}/checks`);
problems.push(...checks.checks.filter((c) => c.status === "fail"));

// Headroom: a campaign that runs out of quota halfway stops halfway.
const { usage } = await api("GET", "/billing");
const left = Math.min(
  (usage.daily_limit ?? Infinity) - usage.emails_today,
  (usage.monthly_limit ?? Infinity) - usage.emails,
);
if (audience.subscribed > left) {
  problems.push({ condition: "quota", message: `${audience.subscribed} contacts, ${left} emails left` });
}

if (problems.length > 0) {
  console.error(problems);
  process.exit(1);
}
if (!go) {
  console.log("All checks pass. Run again with --send to send.");
  process.exit(0);
}

await api(
  "POST",
  `/broadcasts/${id}/send`,
  scheduledAt === undefined ? undefined : { scheduled_at: scheduledAt },
);
const { status } = await api("GET", `/broadcasts/${id}`);
console.log({ id, status });

$ node send.mjs 01a14be7-346d-7cd6-a9b5-104b24f2057f
{
  from: 'Acme <digest@news.acme.example>',
  subject: 'What shipped this month',
  contacts: 1
}
All checks pass. Run again with --send to send.
$ node send.mjs 01a14be7-346d-7cd6-a9b5-104b24f2057f --send
{
  from: 'Acme <digest@news.acme.example>',
  subject: 'What shipped this month',
  contacts: 1
}
{ id: '01a14be7-346d-7cd6-a9b5-104b24f2057f', status: 'queued' }

// report.mjs <broadcast id>: wait until the campaign ends, then list who complained or left.
import { api } from "./rasket.mjs";

const [id] = process.argv.slice(2);
let { status } = await api("GET", `/broadcasts/${id}`);
while (!["sent", "failed", "canceled"].includes(status)) {
  await new Promise((r) => setTimeout(r, 60_000)); // once a minute
  ({ status } = await api("GET", `/broadcasts/${id}`));
}
console.log({ status });

for (const type of ["complained", "unsubscribed"]) {
  const emails = [];
  let cursor = "";
  for (;;) {
    const page = await api("GET", `/broadcasts/${id}/recipients?type=${type}&limit=100${cursor}`);
    emails.push(...page.data.map((r) => r.email));
    if (!page.has_more) break;
    cursor = `&after=${encodeURIComponent(page.data.at(-1).id)}`;
  }
  console.log(type, emails);
}

An agent connected to Rasket’s MCP server signs in with OAuth, so no API key sits in its context; the MCP post covers the connection. Three tools make a campaign: create_broadcast saves the draft, preview_broadcast returns what would go out plus a confirm_token, and send_broadcast refuses without that token. From a real run on another draft:

preview_broadcast { "broadcast_id": "01a148db-d264-7b0d-a107-ebd539218a8e" }
→ {
  "broadcast": { "from": "Acme <digest@news.acme.example>",
                 "subject": "What shipped this month", "status": "draft" },
  "segment": { "name": "Product updates: opted in", "subscribed": 2 },
  "recipients": 2,
  "sendable": true,
  "confirm_token": "1792227338.CjjPg80uPZBKe3Q8LC1eP_322ANQ1DGCrhcn9RbPics",
  "confirm_expires_at": "2026-10-17T08:55:38.000Z"
}

send_broadcast { "broadcast_id": "01a148db-d264-7b0d-a107-ebd539218a8e" }
→ invalid_parameter: "send_broadcast needs a confirm_token. Call preview_broadcast
  for this broadcast, show the person the segment, recipients, subject and sender,
  and send with the token it returns once they confirm."

send_broadcast { "broadcast_id": "01a148db-…", "confirm_token": "1792227338.CjjP…" }
→ { "id": "01a148db-d264-7b0d-a107-ebd539218a8e" }

All three tools need the broadcasts:write scope, which does not include reading: get_broadcast, list_broadcasts and get_broadcast_report need broadcasts:read, and finding a segment with list_segments needs segments:read. A connection made with the plain server URL asks for every tool’s scope, so it holds all of them. No scope lets an app draft a campaign but not send it. Each connected app may send three campaigns per rolling hour (the MCP docs list every tool, scope and limit).

When the model writes the HTML from the changelog, give it the rules in the prompt: plain HTML, one link per item, only {{{FIRST_NAME|there}}}-style variables with a default, and no unsubscribe link. Then check its work before a person sees it. Save the draft, call POST /broadcasts/{id}/checks, hand each fail message back to the model, and repeat until none remain. The messages are written to act on; this is what a send of a bad draft got back:

422 validation_error
"details": { "checks": [
  { "code": "unresolved_variable", "status": "fail",
    "message": "{{{COMPANY}}} is not a contact field or property, so it would be sent
                empty. Check the spelling, or add a default: {{{COMPANY|friend}}}." },
  { "code": "link_scheme", "status": "fail",
    "message": "1 link runs code instead of opening a page: “javascript:alert(1)”.
                Mail clients remove these." }
] }

Never let the agent set acknowledge_checks, the flag that sends despite a failing check. It exists for a person who has read the failures.

If you split streams, send campaigns from news.acme.example and receipts from the root or mail.acme.example; whether the split is worth it at your volume is the subdomain guide’s question. The separation is partial: Google counts a subdomain’s mail toward its parent domain’s bulk-sender total (Google’s sender FAQ, read 2026-10-17), so splitting does not take campaigns out from under the rules your receipts follow. Pick a name that cannot clash with your return path, the subdomain that receives your bounces. A domain added now puts its return path at rasket.<domain>; older domains may use send., so avoid that name for a sending subdomain.

Unless you publish a DMARC record at _dmarc.news.acme.example, receivers apply the root record’s sp= tag, or its p= when there is none (RFC 9989, read 2026-10-17). A new subdomain also has no reputation yet: send the first campaigns to your most recent sign-ups and grow from there, as the warm-up guide lays out, and watch complaints against the thresholds in the complaint rate guide.

Start with postal.mjs once, then put draft.mjs on a monthly schedule with RASKET_TEST_TO set to your own address. Every other field is in the broadcasts reference.