Delete a tag

Removes a tag, or retires it. Which of the two happened is in outcome, and the two are not the same act: one ends the tag, and the other does not. Needs audience: write, and is a write.

deleted. No article was ever addressed to this tag, so it is removed outright and its assignments go with it. Asking for it afterwards answers 404. Creating a tag and changing your mind leaves nothing behind.

retired. An article was addressed to this tag, so the tag is kept and marked retired instead, because the audience of an article that has already been sent does not change retroactively. That has four consequences, and the first is the one to read twice:

• Everyone holding the tag goes on holding it, and goes on being able to read every article it was addressed to, on the web as well as in the inbox, evaluated live on every read rather than settled at send time. tag.known_subscriber_count in the response is what it was, not zero. Retiring a tag revokes nobody's access to anything.
• It stops being offered. It is absent from the tag list unless include_retired=true asks for it, and no new holder can be added, because Apply a tag to a subscriber refuses a retired tag.
• It stays addressable. GET /tags/{tag} resolves it either way, so a client rendering the audience of an article sent last year still finds the name behind the identifier.
• Its name is free for a new tag to take.

If what you want is to take access away, take the tag off the people holding it with Take a tag off a subscriber (DELETE /subscribers/{subscriber}/tags/{tag}), one subscriber at a time. That operation works on a retired tag for exactly this reason. Deleting the tag is not that operation and cannot be made into it.

Retirement is final. Deleting a tag that is already retired answers 200 with the retirement it already made and never removes the row: the holders a retirement kept are the ones still deciding who may read what the tag was addressed to.

Publishes no event.