Win back readers before they leave

Connect once

Add Commune's MCP server to your agent, then approve the consent screen and pick your newsletter. Nothing else to install.

claude mcp add --transport http commune https://api.usecommune.com/mcp

Ask

One prompt does the whole job. Paste it as it is, or change the parts that are yours.

What it uses

Your agent picks these of Commune's tools to answer. You do not name them; they are here so you know where every part of the answer comes from.

• who_is_drifting_away

  Finds readers in the two lowest engagement bands (dormant and reader) whose activity in the last fourteen days fell against the fourteen before, strongest first. Somebody who was always quiet is left out: they are not someone you are losing.

• commune_read

  Looks up each reader's email address and subscription status, so anyone who already unsubscribed is dropped.

• what_are_readers_actually_doing

  Reads the recent opens, reads, likes, highlights and replies behind the scores, which is where "what they stopped doing" comes from.

What comes back

Every request sends Authorization: Bearer $COMMUNE_API_KEY and Commune-Version: 2026-08-26.

1. 1

   Find your newsletter

   A key reaches one newsletter or several, whichever its owner ticked when creating it. List them and pick yours by handle (or id, either works in a path): every other request names it.

   GET/newslettersReference

   cURL

   curl "https://api.usecommune.com/newsletters" \
     -H "Authorization: Bearer $COMMUNE_API_KEY" \
     -H "Commune-Version: 2026-08-26"

   Response 200

   {
     "object": "list",
     "data": [
       {
         "object": "newsletter",
         "id": "7d3f1c02-58a1-4a4e-9a0b-2f6d1c9e4411",
         "handle": "example-letter",
         "name": "The Example Letter",
         "description": "A weekly letter about how newsletters and communities fit together.",
         "esp": "commune",
         "image_url": "https://cdn.example.com/newsletters/example-letter/avatar.png",
         "website_url": "https://example.com",
         "social_links": {
           "twitter": "https://x.com/exampleletter",
           "bluesky": "https://bsky.app/profile/exampleletter.bsky.social"
         },
         "language": "en",
         "chat_create_permission": "subscribers",
         "allow_non_subscriber_chat": false,
         "owner": {
           "object": "user",
           "id": "usr_2Nf8Kq1pWc"
         },
         "featured_article": {
           "object": "article",
           "id": "4c9e2f81-0b7a-4d13-8e55-1a2b3c4d5e6f"
         },
         "created_at": "2025-03-04T10:00:00Z",
         "updated_at": "2026-08-26T09:32:11Z"
       }
     ],
     "pagination": {
       "has_more": false,
       "next_cursor": null
     }
   }

2. 2

   Ask for readers who are cooling off, with their addresses

   Commune scores every reader with a Commune account on what they did in the last fourteen days (t1_score) against the fourteen before (t2_score), and places them on a ladder from dormant to superfan. velocity=cooling keeps the readers whose activity fell, and status, repeated, keeps the two lowest bands: the readers you are about to lose.

   expand=subscriber puts each reader's full subscriber record, email address and subscription status included, in the same response. That is one request per page of up to 100 readers, not one more per reader. It needs audience: read on the key as well as insights: read: without it, the request is refused with 403 insufficient_scope rather than answered without the addresses.

   The list comes back highest total_score first. While pagination.has_more is true, send the same request again with cursor set to pagination.next_cursor.

   GET/newsletters/{newsletter}/insightsReference

   cURL

   curl "https://api.usecommune.com/newsletters/example-letter/insights?velocity=cooling&status=dormant&status=reader&expand=subscriber&limit=100" \
     -H "Authorization: Bearer $COMMUNE_API_KEY" \
     -H "Commune-Version: 2026-08-26"

   Response 200

   {
     "object": "list",
     "data": [
       {
         "object": "subscriber_insight",
         "newsletter": {
           "object": "newsletter",
           "id": "7d3f1c02-58a1-4a4e-9a0b-2f6d1c9e4411"
         },
         "subscriber": {
           "object": "subscriber",
           "id": "44556677-8899-4aa1-b2c3-d4e5f6071829",
           "newsletter": {
             "object": "newsletter",
             "id": "7d3f1c02-58a1-4a4e-9a0b-2f6d1c9e4411"
           },
           "user": {
             "object": "user",
             "id": "usr_2xR8kQ4mN7pL1vB9"
           },
           "email": "[email protected]",
           "status": "subscribed",
           "source": "commune",
           "tags": [],
           "created_at": "2026-02-14T10:31:07Z",
           "synced_at": null
         },
         "total_score": 88,
         "community_score": 88,
         "esp_score": 0,
         "t1_score": 0,
         "t2_score": 12,
         "velocity": "cooling",
         "status": "dormant",
         "share_points": 0,
         "last_action_at": "2026-07-02T09:12:40Z",
         "synced_to_esp_at": null
       }
     ],
     "pagination": {
       "has_more": false,
       "next_cursor": null
     }
   }

3. 3

   Put the sharpest falls first

   Keep the readers who are still subscribed: somebody who already unsubscribed is not drifting, they are gone, and mailing them anyway is the one thing this job must never do. Then sort by how far their activity fell, t2_score - t1_score. The top of that list is who to write to today.

   rank.mjs

   // insights: every page of step 2's data, with subscribers expanded.
   const rows = insights
     .filter((insight) => insight.subscriber.status === "subscribed")
     .map((insight) => ({
       email: insight.subscriber.email,
       fell_by: insight.t2_score - insight.t1_score,
       last_action_at: insight.last_action_at,
     }))
     .sort((a, b) => b.fell_by - a.fell_by);

4. 4

   Send the list where you follow up

   The list is only useful where you will act on it: a CSV for your email tool, a row per reader in your CRM, or a message in the channel where your team works. This posts it to a Slack incoming webhook; swap the last call for whatever you use.

   Write to them one by one, not as another broadcast. A short personal note that asks what changed does more than a newsletter they have already stopped opening.

   notify.mjs

   const lines = rows
     .slice(0, 20)
     .map((row) => `• ${row.email}: activity down ${row.fell_by} points, last seen ${row.last_action_at.slice(0, 10)}`);
   
   await fetch(process.env.SLACK_WEBHOOK_URL, {
     method: "POST",
     headers: { "content-type": "application/json" },
     body: JSON.stringify({
       text: `${rows.length} readers are going quiet this week:\n${lines.join("\n")}`,
     }),
   });

5. 5

   Run it every Monday

   Scores move daily, and a weekly list is the rhythm most people can act on. Any scheduler works. This is a GitHub Actions workflow that runs the script below at 08:00 UTC every Monday, with the key and the Slack URL kept as repository secrets.

   Next Monday's list is also how you see who came back: a reader you wrote to who is no longer on it has warmed up again.

   .github/workflows/win-back.yml

   name: Win back readers
   on:
     schedule:
       - cron: "0 8 * * 1"
     workflow_dispatch:
   jobs:
     run:
       runs-on: ubuntu-latest
       steps:
         - uses: actions/checkout@v4
         - uses: actions/setup-node@v4
           with:
             node-version: 20
         - run: node win-back.mjs
           env:
             COMMUNE_API_KEY: ${{ secrets.COMMUNE_API_KEY }}
             COMMUNE_NEWSLETTER: ${{ vars.COMMUNE_NEWSLETTER }}
             SLACK_WEBHOOK_URL: ${{ secrets.SLACK_WEBHOOK_URL }}

const BASE = "https://api.usecommune.com";
const VERSION = "2026-08-26";
const KEY = process.env.COMMUNE_API_KEY;

async function api(path) {
  const res = await fetch(BASE + path, {
    headers: { authorization: `Bearer ${KEY}`, "commune-version": VERSION },
  });
  if (res.status === 429) {
    await new Promise((r) => setTimeout(r, Number(res.headers.get("retry-after") ?? 5) * 1000));
    return api(path);
  }
  const body = await res.json();
  if (!res.ok) {
    const { code, message, request_id } = body.error;
    throw new Error(`${res.status} ${code}: ${message} (request ${request_id})`);
  }
  return body;
}

async function* all(path) {
  let cursor = null;
  do {
    const sep = path.includes("?") ? "&" : "?";
    const page = await api(cursor ? `${path}${sep}cursor=${encodeURIComponent(cursor)}` : path);
    yield* page.data;
    cursor = page.pagination.next_cursor;
  } while (cursor);
}

// 1. The newsletter to work on. A key can reach several newsletters, so
//    COMMUNE_NEWSLETTER picks one by handle; a key that reaches exactly one
//    uses it without being told.
const { data: newsletters } = await api("/newsletters");
const wanted = process.env.COMMUNE_NEWSLETTER;
const newsletter = wanted
  ? newsletters.find((n) => n.handle === wanted || n.id === wanted)
  : newsletters.length === 1 ? newsletters[0] : null;
if (!newsletter) {
  throw new Error(
    wanted
      ? "This key does not reach " + wanted + "."
      : "This key reaches " + newsletters.length + " newsletters. Set COMMUNE_NEWSLETTER to one handle.",
  );
}

// 2. Readers you are about to lose, with their subscriber records inlined.
const query = "velocity=cooling&status=dormant&status=reader&expand=subscriber&limit=100";
const insights = [];
for await (const insight of all(`/newsletters/${newsletter.handle}/insights?${query}`)) {
  insights.push(insight);
}

// 3. Still subscribed only, sharpest fall first.
const rows = insights
  .filter((insight) => insight.subscriber.status === "subscribed")
  .map((insight) => ({
    email: insight.subscriber.email,
    fell_by: insight.t2_score - insight.t1_score,
    last_action_at: insight.last_action_at,
  }))
  .sort((a, b) => b.fell_by - a.fell_by);

// 4. Where you follow up.
const lines = rows
  .slice(0, 20)
  .map((row) => `• ${row.email}: activity down ${row.fell_by} points, last seen ${row.last_action_at.slice(0, 10)}`);
await fetch(process.env.SLACK_WEBHOOK_URL, {
  method: "POST",
  headers: { "content-type": "application/json" },
  body: JSON.stringify({
    text: `${rows.length} readers are going quiet this week:\n${lines.join("\n")}`,
  }),
});