Erase a subscriber

Erases this subscription. Needs audience: write, is a write, and requires a request body confirming the erasure.

This is an erasure, not an unsubscribe, and it cannot be undone. The subscriber record goes, and everything keyed on it goes with it: the tags they held, their per-article delivery rows, and any automation run that named them, along with the automation emails those runs sent. The newsletter's send totals are counters and do not move, but "did this person open that article" stops having an answer. It is the call for somebody exercising a right to erasure.

To stop mailing somebody, set their status instead (PATCH /subscribers/{subscriber} with {"status": "unsubscribed"}). That keeps the record, so a bounce or a complaint on the address is remembered and Commune does not mail it again by accident, and a reader who comes back reuses the same row. It is also reversible, and this is not.

The confirmation

Send {"confirm": "erase_subscriber_and_history"}. Without it, or with any other value, the request is refused 400 with param set to confirm and allowed_values holding the one accepted string, and nothing is erased: the subscriber, the tags they hold and their delivery history are all exactly as they were.

The refusal is not a formality to route around. It exists because this call and PATCH /subscribers/{subscriber} read alike and do not undo alike, so an integration reaching for "remove this subscriber" lands here by default and loses the record of everything that was ever sent to that person. If what you want is for the newsletter to stop reaching somebody, the status write is the call, and it is the one to reach for when you are not sure.

A change in the contract as of this version, with no compatibility fallback. A DELETE that sent no body succeeded before and is refused 400 now. An integration that erases subscribers has to send the confirmation; one that wanted an unsubscribe was reaching for the wrong call and the refusal names the right one.

Publishes subscriber.unsubscribed with reason: removed, before the row goes, and only when the subscriber was still subscribed. Deleting somebody who had already unsubscribed, bounced or complained publishes nothing: they did not stop being mailable, they already had. Reconcile a mirror of the list against GET /newsletters/{newsletter}/subscribers rather than against this topic alone.

Answers the subscriber as it last stood, so the response is a record of what was removed rather than an empty body. It is a receipt and not a lookup: a GET on the same id answers 404 from here on. The same address can be added again afterwards, as a new subscription with a new id and no history.