Tag a reader the moment they act

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.

• commune_read

  Reads the trigger catalog, which is what says that this topic's events are about a subscriber and which properties a filter may name under it. A filter on a property the payload does not carry would match every event.

• commune_write

  Creates the tag, writes the graph as a draft, sends the test copy, and turns the automation on when you ask. A draft sends nothing.

• who_is_drifting_away

  Answers how many readers are cooling off right now, which is the size of the group this automation will start reaching.

What comes back

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

1. 1

   Make the tag the automation will apply

   A tag step names a tag by id, so the tag has to exist first. A step naming a tag that has been deleted is refused: it would do nothing, every run, forever.

   The name has to be unique among the newsletter's live tags, so creating one that already exists answers 409 rather than quietly handing you the existing one. known_subscriber_count starts at zero and is what you will watch.

   It is a tag like any other: you can see it in Commune, apply it by hand, and send an article to it. The automation is just another thing that moves it.

   POST/newsletters/{newsletter}/tagsReference

   cURL

   curl -X POST "https://api.usecommune.com/newsletters/example-letter/tags" \
     -H "Authorization: Bearer $COMMUNE_API_KEY" \
     -H "Commune-Version: 2026-08-26" \
     -H "Idempotency-Key: going-quiet-tag-2026-10-09" \
     -H "Content-Type: application/json" \
     -d '{
     "name": "Going quiet"
   }'

   Response 201

   {
     "object": "tag",
     "id": "cc33dd44-ee55-4f66-8a77-b8c9d0e1f203",
     "newsletter": {
       "object": "newsletter",
       "id": "7d3f1c02-58a1-4a4e-9a0b-2f6d1c9e4411"
     },
     "name": "Going quiet",
     "known_subscriber_count": 0,
     "is_room": false,
     "retired": false,
     "retired_at": null,
     "created_at": "2026-10-09T15:18:00Z"
   }

2. 2

   Write it, filtered to the readers you actually mean

   The trigger is a reader crossing a boundary in the newsletter's engagement ladder. That event fires in both directions, so an automation on it with no filter would send this email to somebody who had just started reading everything.

   trigger_filter is what stops that. It is a JSON Schema document in the same closed subset a condition step uses, and it decides whether an event starts a run at all. The paths in it are the event payload's own, not the three-branch context a condition is evaluated against, because a filter runs before there is a run to have a context. direction is promoted or demoted, and this one keeps the demotions.

   required is doing real work there. An absent property says nothing in JSON Schema, so properties on its own would also match a payload carrying no direction at all.

   The graph is three steps wired one to the next, and the last one wires nothing, which is what ends the run. mark-quiet moves the tag on the subscriber the run is about. settle parks the run for two days, written as an ISO 8601 duration: there is no time-of-day field, because Commune does not know a subscriber's time zone and a time of day would be interpreted in UTC. reach-out sends the email, with the unsubscribe link and {{ address }} that Commune refuses to send without.

   reentry: true because this is not a welcome. A reader can cool off, come back, and cool off again two years later, and the note is worth sending both times. The default is false, which means once ever.

   POST/newsletters/{newsletter}/automationsReference

   cURL

   curl -X POST "https://api.usecommune.com/newsletters/example-letter/automations" \
     -H "Authorization: Bearer $COMMUNE_API_KEY" \
     -H "Commune-Version: 2026-08-26" \
     -H "Idempotency-Key: going-quiet-automation-2026-10-09" \
     -H "Content-Type: application/json" \
     -d '{
     "name": "Reach out when a reader cools off",
     "trigger": "subscriber.status_changed",
     "trigger_filter": {
       "properties": {
         "direction": {
           "const": "demoted"
         }
       },
       "required": [
         "direction"
       ]
     },
     "reentry": true,
     "steps": [
       {
         "id": "mark-quiet",
         "type": "add_tag",
         "tag": "cc33dd44-ee55-4f66-8a77-b8c9d0e1f203",
         "next": "settle"
       },
       {
         "id": "settle",
         "type": "wait",
         "duration": "P2D",
         "next": "reach-out"
       },
       {
         "id": "reach-out",
         "type": "send_email",
         "email": {
           "subject": "Still want this, {{ subscriber.first_name }}?",
           "preview_text": "One line back is enough.",
           "body_markdown": "# Still want this?\n\nYou used to read most of these and have not opened one in a while, which\nis fine. If the letter has drifted away from what you signed up for, tell\nme. A one-line reply is worth more to me than any survey.\n\n[Unsubscribe]({{ unsubscribe_url }}) · {{ address }}\n"
         }
       }
     ]
   }'

   Response 201

   {
     "object": "automation",
     "id": "2d4f6a81-3b5c-4d7e-8f90-a1b2c3d4e5f6",
     "newsletter": {
       "object": "newsletter",
       "id": "7d3f1c02-58a1-4a4e-9a0b-2f6d1c9e4411"
     },
     "name": "Reach out when a reader cools off",
     "status": "draft",
     "trigger": "subscriber.status_changed",
     "trigger_filter": {
       "properties": {
         "direction": {
           "const": "demoted"
         }
       },
       "required": [
         "direction"
       ]
     },
     "reentry": true,
     "steps": [
       {
         "id": "mark-quiet",
         "type": "add_tag",
         "next": "settle",
         "then": null,
         "else": null,
         "duration": null,
         "tag": "cc33dd44-ee55-4f66-8a77-b8c9d0e1f203",
         "schema": null,
         "email": null
       },
       {
         "id": "settle",
         "type": "wait",
         "next": "reach-out",
         "then": null,
         "else": null,
         "duration": "P2D",
         "tag": null,
         "schema": null,
         "email": null
       },
       {
         "id": "reach-out",
         "type": "send_email",
         "next": null,
         "then": null,
         "else": null,
         "duration": null,
         "tag": null,
         "schema": null,
         "email": {
           "subject": "Still want this, {{ subscriber.first_name }}?",
           "preview_text": "One line back is enough.",
           "body_markdown": "# Still want this?\n\nYou used to read most of these and have not opened one in a while, which\nis fine. If the letter has drifted away from what you signed up for, tell\nme. A one-line reply is worth more to me than any survey.\n\n[Unsubscribe]({{ unsubscribe_url }}) · {{ address }}\n"
         }
       }
     ],
     "created_at": "2026-10-09T15:20:00Z",
     "updated_at": "2026-10-09T15:20:00Z",
     "activated_at": null
   }

3. 3

   Turn it on

   Read a test copy of reach-out first. The step is the same one Welcome every new reader walks through, and the reason is the same: there is no moment at which anybody watches an automation email go out, so without a test copy the first person to see it rendered is a reader you are already at risk of losing.

   Every gate runs again here on the stored automation: the graph, the filter, the email's footer, every image in it, and the newsletter's own ability to send. Each is a 422 naming what is wrong. The newsletter checks apply only because this graph sends; an automation that only moved the tag would be turned on without them.

   It reacts to the next crossing, not to the backlog. Readers who were already cooling off before you turned this on are not tagged retrospectively. If you want to reach them once, that is a list and a one-off email rather than a standing instruction, and Win back readers is that page.

   This installs a standing instruction

   From the moment it returns, Commune emails whoever the trigger names, as often as it fires, with no further request from anybody. It is charged to a daily cap counted per newsletter, reported as a 429 whose Retry-After is measured in hours rather than seconds.

   POST/automations/{automation}/activateReference

   cURL

   curl -X POST "https://api.usecommune.com/automations/2d4f6a81-3b5c-4d7e-8f90-a1b2c3d4e5f6/activate" \
     -H "Authorization: Bearer $COMMUNE_API_KEY" \
     -H "Commune-Version: 2026-08-26" \
     -H "Idempotency-Key: going-quiet-activate-2026-10-09"

   Response 200

   {
     "object": "automation",
     "id": "2d4f6a81-3b5c-4d7e-8f90-a1b2c3d4e5f6",
     "newsletter": {
       "object": "newsletter",
       "id": "7d3f1c02-58a1-4a4e-9a0b-2f6d1c9e4411"
     },
     "name": "Reach out when a reader cools off",
     "status": "active",
     "trigger": "subscriber.status_changed",
     "trigger_filter": {
       "properties": {
         "direction": {
           "const": "demoted"
         }
       },
       "required": [
         "direction"
       ]
     },
     "reentry": true,
     "steps": [
       {
         "id": "mark-quiet",
         "type": "add_tag",
         "next": "settle",
         "then": null,
         "else": null,
         "duration": null,
         "tag": "cc33dd44-ee55-4f66-8a77-b8c9d0e1f203",
         "schema": null,
         "email": null
       },
       {
         "id": "settle",
         "type": "wait",
         "next": "reach-out",
         "then": null,
         "else": null,
         "duration": "P2D",
         "tag": null,
         "schema": null,
         "email": null
       },
       {
         "id": "reach-out",
         "type": "send_email",
         "next": null,
         "then": null,
         "else": null,
         "duration": null,
         "tag": null,
         "schema": null,
         "email": {
           "subject": "Still want this, {{ subscriber.first_name }}?",
           "preview_text": "One line back is enough.",
           "body_markdown": "# Still want this?\n\nYou used to read most of these and have not opened one in a while, which\nis fine. If the letter has drifted away from what you signed up for, tell\nme. A one-line reply is worth more to me than any survey.\n\n[Unsubscribe]({{ unsubscribe_url }}) · {{ address }}\n"
         }
       }
     ],
     "created_at": "2026-10-09T15:20:00Z",
     "updated_at": "2026-10-09T15:20:00Z",
     "activated_at": "2026-10-09T15:41:00Z"
   }

4. 4

   Watch the tag move, and watch for the loop

   Every tag the automation applies publishes subscriber.tagged, exactly as a tag applied by hand does, with one difference worth all of this paragraph: actor names the run that caused it.

   That attribution is what the loop guard reads. A run started by this event inherits this run's chain plus this run's own automation, and two things are then refused before a run exists: a chain that already contains that automation, which is a cycle of any length; and a chain already five automations deep. So an automation triggered by subscriber.tagged whose steps add a tag loops immediately on paper and is refused in practice.

   Nothing is published for a run the guard refused, because no run was created and there would be no run id to name. A refusal therefore looks exactly like an automation nobody switched on. If you build a second automation on this tag and it never fires, this is the first thing to check, before the trigger, the filter and the key.

   data.chain_depth on every automation.run.* message says how many automations' actions led to that run: zero for one a person caused, one for a run started by what another automation did.

   Commune posts subscriber.tagged to your endpoint:

   event subscriber.tagged

   {
     "id": "018f2a94-1010-7000-8000-000000000101",
     "type": "subscriber.tagged",
     "api_version": "2026-08-26",
     "occurred_at": "2026-10-10T06:12:00Z",
     "newsletter_id": "7d3f1c02-58a1-4a4e-9a0b-2f6d1c9e4411",
     "actor": {
       "type": "system",
       "id": "4e5f6a7b-8c9d-4e0f-8a1b-2c3d4e5f6a7b",
       "label": "automation: Reach out when a reader cools off"
     },
     "idempotency_key": null,
     "data": {
       "subscriber_id": "33445566-7788-4990-a1b2-c3d4e5f60718",
       "email": "[email protected]",
       "tag_id": "cc33dd44-ee55-4f66-8a77-b8c9d0e1f203",
       "tag_name": "Going quiet",
       "direction": "assigned"
     }
   }

5. 5

   Ask who is in the group

   The tag is an ordinary tag, so this is the ordinary question. ?tag= takes the tag's id and ?status=subscribed keeps the people the newsletter can still reach, which is the filter you want on a group defined by having gone quiet: an unsubscribe does not remove somebody's tags.

   This needs audience: read on top of the sending permission, because it returns email addresses. The automation's own runs do not: a run is read under sending and carries no address at all, which is why there are two permissions on this page rather than one.

   To see where each of those readers is in the sequence instead, list the automation's runs. ?status=waiting is the readers sitting on the two-day wait, which is the group that has been tagged and not yet written to.

   GET/newsletters/{newsletter}/subscribersReference

   cURL

   curl "https://api.usecommune.com/newsletters/example-letter/subscribers?tag=cc33dd44-ee55-4f66-8a77-b8c9d0e1f203&status=subscribed&limit=100" \
     -H "Authorization: Bearer $COMMUNE_API_KEY" \
     -H "Commune-Version: 2026-08-26"

   Response 200

   {
     "object": "list",
     "data": [
       {
         "object": "subscriber",
         "id": "33445566-7788-4990-a1b2-c3d4e5f60718",
         "newsletter": {
           "object": "newsletter",
           "id": "7d3f1c02-58a1-4a4e-9a0b-2f6d1c9e4411"
         },
         "user": {
           "object": "user",
           "id": "usr_2xR8kQ4mN7pL1vB9"
         },
         "email": "[email protected]",
         "status": "subscribed",
         "source": "commune",
         "tags": [
           {
             "object": "tag",
             "id": "cc33dd44-ee55-4f66-8a77-b8c9d0e1f203"
           }
         ],
         "created_at": "2026-02-14T10:31:07Z",
         "synced_at": null
       }
     ],
     "pagination": {
       "has_more": false,
       "next_cursor": null
     }
   }

6. 6

   Stop it without losing anybody's place

   A pause holds every waiting run exactly where it is. A reader one day into the two-day wait stays on that step and resumes from it when you turn the automation back on, so there is no window in which a paused automation still sends and no drain to wait out.

   That is the difference from archiving, which is what deleting an automation does. An archive ends the runs it was in the middle of, with an exit_reason saying so, because an archive is not coming back and a run holding its place on a graph nobody will activate again is a subscriber stuck part way through forever. There is no way back from archived: write a new automation instead.

   Pausing a paused automation succeeds and changes nothing. A draft or an archived one is refused, because neither is sending and there is nothing to pause.

   The tag stays where it is either way. Pausing stops the automation, not the segment, so the readers it has already tagged are still in the group and still reachable by hand.

   POST/automations/{automation}/pauseReference

   cURL

   curl -X POST "https://api.usecommune.com/automations/2d4f6a81-3b5c-4d7e-8f90-a1b2c3d4e5f6/pause" \
     -H "Authorization: Bearer $COMMUNE_API_KEY" \
     -H "Commune-Version: 2026-08-26" \
     -H "Idempotency-Key: going-quiet-pause-2026-12-01"

   Response 200

   {
     "object": "automation",
     "id": "2d4f6a81-3b5c-4d7e-8f90-a1b2c3d4e5f6",
     "newsletter": {
       "object": "newsletter",
       "id": "7d3f1c02-58a1-4a4e-9a0b-2f6d1c9e4411"
     },
     "name": "Reach out when a reader cools off",
     "status": "paused",
     "trigger": "subscriber.status_changed",
     "trigger_filter": {
       "properties": {
         "direction": {
           "const": "demoted"
         }
       },
       "required": [
         "direction"
       ]
     },
     "reentry": true,
     "steps": [
       {
         "id": "mark-quiet",
         "type": "add_tag",
         "next": "settle",
         "then": null,
         "else": null,
         "duration": null,
         "tag": "cc33dd44-ee55-4f66-8a77-b8c9d0e1f203",
         "schema": null,
         "email": null
       },
       {
         "id": "settle",
         "type": "wait",
         "next": "reach-out",
         "then": null,
         "else": null,
         "duration": "P2D",
         "tag": null,
         "schema": null,
         "email": null
       },
       {
         "id": "reach-out",
         "type": "send_email",
         "next": null,
         "then": null,
         "else": null,
         "duration": null,
         "tag": null,
         "schema": null,
         "email": {
           "subject": "Still want this, {{ subscriber.first_name }}?",
           "preview_text": "One line back is enough.",
           "body_markdown": "# Still want this?\n\nYou used to read most of these and have not opened one in a while, which\nis fine. If the letter has drifted away from what you signed up for, tell\nme. A one-line reply is worth more to me than any survey.\n\n[Unsubscribe]({{ unsubscribe_url }}) · {{ address }}\n"
         }
       }
     ],
     "created_at": "2026-10-09T15:20:00Z",
     "updated_at": "2026-10-09T15:20:00Z",
     "activated_at": "2026-10-09T15:41:00Z"
   }

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

async function api(path, { method = "GET", body, idempotencyKey } = {}) {
  const res = await fetch(BASE + path, {
    method,
    headers: {
      authorization: `Bearer ${KEY}`,
      "commune-version": VERSION,
      ...(body ? { "content-type": "application/json" } : {}),
      ...(idempotencyKey ? { "idempotency-key": idempotencyKey } : {}),
    },
    body: body ? JSON.stringify(body) : undefined,
  });
  const answer = await res.json();
  if (!res.ok) {
    const { code, message, request_id } = answer.error;
    throw new Error(`${res.status} ${code}: ${message} (request ${request_id})`);
  }
  return answer;
}

const TAG_NAME = "Going quiet";

// 1. The tag. A name has to be unique among the live tags, so a second run
//    answers 409 rather than making a duplicate; reuse what is there.
const { data: tags } = await api(`/newsletters/${NEWSLETTER}/tags`);
const existing = tags.find((tag) => tag.name === TAG_NAME);
const tag =
  existing ??
  (await api(`/newsletters/${NEWSLETTER}/tags`, {
    method: "POST",
    idempotencyKey: "going-quiet-tag-v1",
    body: { name: TAG_NAME },
  }));
console.log(`Tag ${tag.id} (${tag.known_subscriber_count} readers).`);

// 2. The automation. The filter runs against the event's own payload before
//    a run exists, which is why it names `direction` rather than anything
//    under `subscriber`. Without `required`, a payload with no `direction`
//    would match: an absent property says nothing in JSON Schema.
const draft = await api(`/newsletters/${NEWSLETTER}/automations`, {
  method: "POST",
  idempotencyKey: "going-quiet-automation-v1",
  body: {
    name: "Reach out when a reader cools off",
    trigger: "subscriber.status_changed",
    trigger_filter: {
      properties: { direction: { const: "demoted" } },
      required: ["direction"],
    },
    reentry: true,
    steps: [
      { id: "mark-quiet", type: "add_tag", tag: tag.id, next: "settle" },
      { id: "settle", type: "wait", duration: "P2D", next: "reach-out" },
      {
        id: "reach-out",
        type: "send_email",
        email: {
          subject: "Still want this, {{ subscriber.first_name }}?",
          preview_text: "One line back is enough.",
          body_markdown: process.env.REACH_OUT_BODY,
        },
      },
    ],
  },
});

// 3. Read it before a reader does.
const test = await api(`/automations/${draft.id}/steps/reach-out/send-test`, {
  method: "POST",
  idempotencyKey: "going-quiet-test-v1",
  body: { to: [process.env.REVIEW_ADDRESS] },
});
console.log(`Test copy: sent ${test.sent}, failed ${test.failed}.`);

console.log(
  `Draft ${draft.id} is written and NOT sending. When you are happy:\n` +
    `  POST ${BASE}/automations/${draft.id}/activate`,
);