Apply a tag to many subscribers

Puts up to 500 subscribers in this segment in one request, and says what became of each. Needs audience: write, and is a write.

Use this when you have a list, such as a weekly job tagging this week's superfans from GET /newsletters/{newsletter}/insights. It is one request against your rate limit however many subscribers it names, where Apply a tag to a subscriber (POST /subscribers/{subscriber}/tags/{tag}) is one request per subscriber. Use that one for a single subscriber: it answers 404 for an id that is not there, which is the clearer answer when there is only one.

A tag decides what a person can read, not only who receives what. An article addressed to a tag is readable by the people holding it and by nobody else, on the web as well as in the inbox. Applying one grants each subscriber named access to every article that segment was ever addressed to, including articles sent before this call.

subscribers holds 1 to 500 subscriber ids, the id of each Subscriber. A list that is empty, longer than 500, or holds anything that is not a UUID answers 400 and changes nothing. An id repeated in the list counts once and is reported once. The 500 counts the list as sent, repeats included.

Outcomes are per subscriber, not all or nothing. Every id in the list comes back in exactly one of three lists:

• tagged: holds the tag now and did not before.
• already_tagged: held it already. Nothing changes for them, which is a success, exactly as it is for the single operation.
• not_found: not a subscriber of the tag's newsletter. Nothing is written for them and the rest of the list is unaffected. An id from another newsletter and an id that exists nowhere are reported the same way. Retrying them will not help: check where the ids came from.

The request is refused as a whole only for something true of the whole request. A retired tag answers 422 and tags nobody: a retirement stops a segment gaining members while it goes on deciding who may read the articles it was addressed to. A tag this credential cannot reach answers 404.

Retrying is safe. Send the same Idempotency-Key and the same list and you get the first answer back, replayed, with nothing done twice. A new key with the same list is a new request: everyone the first one tagged comes back in already_tagged, and nothing is published again.

The response is the tag and three lists of ids, never a Subscriber, so this operation never puts an email address in a response.

Publishes subscriber.tagged with direction: assigned once for each subscriber in tagged, each its own event, all carrying this request's actor and idempotency_key. Nothing is published for already_tagged or not_found. The events are written in the same transaction as the tags, so they exist if and only if the tags do.