{
  "info": {
    "name": "Commune: Find and reward your superfans",
    "description": "A few readers open everything, reply, highlight and share. They are the reason a newsletter grows, and they rarely hear back. Commune scores every reader on what they do in the inbox and in the community, so you can name your superfans, keep them in one group, and thank them with something the rest of the list does not get.\n\nThe walkthrough: https://usecommune.dev/use-cases/reward-your-superfans\n\nSet the `apiKey` variable to a key from https://usecommune.com/settings/api-keys, then run the requests in order.",
    "schema": "https://schema.getpostman.com/json/collection/v2.1.0/collection.json"
  },
  "auth": {
    "type": "bearer",
    "bearer": [
      {
        "key": "token",
        "value": "{{apiKey}}",
        "type": "string"
      }
    ]
  },
  "variable": [
    {
      "key": "baseUrl",
      "value": "https://api.usecommune.com"
    },
    {
      "key": "apiKey",
      "value": ""
    },
    {
      "key": "version",
      "value": "2026-08-26"
    },
    {
      "key": "newsletter",
      "value": "example-letter"
    },
    {
      "key": "tag",
      "value": "cc33dd44-ee55-4f66-8a77-112233445566"
    }
  ],
  "item": [
    {
      "name": "1. Find your newsletter",
      "request": {
        "method": "GET",
        "header": [
          {
            "key": "Commune-Version",
            "value": "{{version}}"
          }
        ],
        "url": {
          "raw": "{{baseUrl}}/newsletters",
          "host": [
            "{{baseUrl}}"
          ],
          "path": [
            "newsletters"
          ]
        },
        "description": "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): the requests below name it."
      }
    },
    {
      "name": "2. Ask for your superfans",
      "request": {
        "method": "GET",
        "header": [
          {
            "key": "Commune-Version",
            "value": "{{version}}"
          }
        ],
        "url": {
          "raw": "{{baseUrl}}/newsletters/{{newsletter}}/insights?status=superfan&limit=100",
          "host": [
            "{{baseUrl}}"
          ],
          "path": [
            "newsletters",
            "{{newsletter}}",
            "insights"
          ],
          "query": [
            {
              "key": "status",
              "value": "superfan"
            },
            {
              "key": "limit",
              "value": "100"
            }
          ]
        },
        "description": "Commune places every scored reader on a ladder from `dormant` to `superfan`, from what they did in the inbox (`esp_score`) and in the community (`community_score`). `status=superfan` keeps the top band. The band is assigned by rank within your newsletter, not by a fixed score, so it is always your own top readers whatever the size of your list.\n\nThe list comes back highest `total_score` first, 100 at a time. While `pagination.next_cursor` is set, send the same request again with `cursor` set to it."
      }
    },
    {
      "name": "3. Look for a Superfans tag",
      "request": {
        "method": "GET",
        "header": [
          {
            "key": "Commune-Version",
            "value": "{{version}}"
          }
        ],
        "url": {
          "raw": "{{baseUrl}}/newsletters/{{newsletter}}/tags?limit=100",
          "host": [
            "{{baseUrl}}"
          ],
          "path": [
            "newsletters",
            "{{newsletter}}",
            "tags"
          ],
          "query": [
            {
              "key": "limit",
              "value": "100"
            }
          ]
        },
        "description": "A tag is a segment of your audience. Look through the live tags for one called `Superfans` before making one: a name a live tag already has is refused. The list is alphabetical and each tag carries `known_subscriber_count`, the people currently subscribed who hold it.\n\nThe first time the job runs there is none, as here. Every run after that finds it, so keep its `id`."
      }
    },
    {
      "name": "4. Create it, once",
      "request": {
        "method": "POST",
        "header": [
          {
            "key": "Commune-Version",
            "value": "{{version}}"
          },
          {
            "key": "Idempotency-Key",
            "value": "{{$guid}}"
          },
          {
            "key": "Content-Type",
            "value": "application/json"
          }
        ],
        "url": {
          "raw": "{{baseUrl}}/newsletters/{{newsletter}}/tags",
          "host": [
            "{{baseUrl}}"
          ],
          "path": [
            "newsletters",
            "{{newsletter}}",
            "tags"
          ]
        },
        "body": {
          "mode": "raw",
          "raw": "{\n  \"name\": \"Superfans\"\n}",
          "options": {
            "raw": {
              "language": "json"
            }
          }
        },
        "description": "A new tag starts empty: nobody holds it and no article is addressed to it, so creating one gives nobody access to anything. It is a write, so it needs an `Idempotency-Key`. Send the same key again to retry safely; Commune replays the first answer instead of making a second tag. A different request under a key you already used answers `409`.\n\nIf a tag named `Superfans` already exists, this answers `422` rather than making a duplicate, which is why step 3 comes first."
      }
    },
    {
      "name": "5. Give each superfan the tag",
      "request": {
        "method": "POST",
        "header": [
          {
            "key": "Commune-Version",
            "value": "{{version}}"
          },
          {
            "key": "Idempotency-Key",
            "value": "{{$guid}}"
          },
          {
            "key": "Content-Type",
            "value": "application/json"
          }
        ],
        "url": {
          "raw": "{{baseUrl}}/tags/{{tag}}/subscribers",
          "host": [
            "{{baseUrl}}"
          ],
          "path": [
            "tags",
            "{{tag}}",
            "subscribers"
          ]
        },
        "body": {
          "mode": "raw",
          "raw": "{\n  \"subscribers\": [\n    \"33445566-7788-4990-a1b2-c3d4e5f60718\",\n    \"44556677-8899-4aa1-b2c3-d4e5f6071829\",\n    \"9f1e2d3c-4b5a-4c6d-8e7f-0a1b2c3d4e5f\"\n  ]\n}",
          "options": {
            "raw": {
              "language": "json"
            }
          }
        },
        "description": "Send this week's superfans to the tag in one request: up to 500 subscriber ids in `subscribers`, with one `Idempotency-Key` for the batch. More than 500 superfans means one request per 500, each with its own key. A retry with the same key and the same list replays the first answer and does nothing twice.\n\nEvery id comes back in exactly one of three lists. `tagged` holds the tag now and did not before. `already_tagged` held it already, which is a success: nothing changes for them, so the weekly job can send the whole list every time. `not_found` is not a subscriber of this newsletter, and nothing is written for them. Retrying those will not help; check where the ids came from (a superfan id from step 2 should never land there). `tag` is the tag as it stands after the write, so `known_subscriber_count` already includes the new holders. A retired tag answers `422` and tags nobody.\n\n**A tag decides what a person can read, not only who receives what.** Once an article is addressed to Superfans, holding the tag is what lets somebody read it, on the web as well as in the inbox, including issues sent before they got the tag. That is also why this job only adds: taking the tag off a reader who slipped out of the band would take away what you already gave them. Remove it deliberately, with `DELETE /subscribers/{subscriber}/tags/{tag}`, if that is what you want."
      }
    },
    {
      "name": "6. See who holds it",
      "request": {
        "method": "GET",
        "header": [
          {
            "key": "Commune-Version",
            "value": "{{version}}"
          }
        ],
        "url": {
          "raw": "{{baseUrl}}/newsletters/{{newsletter}}/subscribers?tag=cc33dd44-ee55-4f66-8a77-112233445566&limit=100",
          "host": [
            "{{baseUrl}}"
          ],
          "path": [
            "newsletters",
            "{{newsletter}}",
            "subscribers"
          ],
          "query": [
            {
              "key": "tag",
              "value": "cc33dd44-ee55-4f66-8a77-112233445566"
            },
            {
              "key": "limit",
              "value": "100"
            }
          ]
        },
        "description": "The segment as it stands, with the address of each reader in it. `tag` narrows the subscribers to the ones holding it, and the list only includes people still `subscribed` unless you ask for other states. This is also the export: a CSV of these addresses is what most other tools will take."
      }
    },
    {
      "name": "7. Send them something nobody else gets",
      "request": {
        "method": "GET",
        "header": [
          {
            "key": "Commune-Version",
            "value": "{{version}}"
          }
        ],
        "url": {
          "raw": "{{baseUrl}}/newsletters/{{newsletter}}/articles?tag=cc33dd44-ee55-4f66-8a77-112233445566&status=sent",
          "host": [
            "{{baseUrl}}"
          ],
          "path": [
            "newsletters",
            "{{newsletter}}",
            "articles"
          ],
          "query": [
            {
              "key": "tag",
              "value": "cc33dd44-ee55-4f66-8a77-112233445566"
            },
            {
              "key": "status",
              "value": "sent"
            }
          ]
        },
        "description": "A thank-you note, an early look at the next issue, a subscriber-only essay. An article addressed to a tag goes only to the subscribers holding it, and only they can read it on the web afterwards.\n\n**The API does not address an article to a tag.** Creating an article takes a title, preview text, cover, slug and body, and sending one takes no audience, so there is no field to set. Write the issue wherever you like (through the API, as a draft, if you want), then open it in the [Commune editor](https://usecommune.com/dashboard/articles), choose **Superfans** as its audience and send it from there.\n\nWhat the API does give you is the record. `tag` on the article list returns only the articles addressed to that segment, so you can see what your superfans have received and read how each one did."
      }
    }
  ]
}