Add a subscriber

Puts an address on this newsletter's list. Needs audience: write, and is a write.

This is not an import, and it is the call a welcome sequence listens for. It publishes subscriber.created, which is the topic automations trigger on, so every address added here enters whatever welcome sequence the newsletter has running. An import and the daily provider sync deliberately publish no such event, so a list migrated in never gets welcomed; calling this in a loop over a list you already have is how you undo that, one email at a time. Move a list with an import.

An address already on the list is not an error. A signup form cannot know whether the person in front of it subscribed last year, so:

• Already subscribed: nothing changes, nothing is published, and the answer is 200 with the subscriber as it stands.
• unsubscribed or bounced: the subscription is reactivated and the answer is 200. This publishes subscriber.created with resubscribed: true, which automations treat as not a new subscriber, so nobody is welcomed twice.
• complained: refused with 422. The reader told a mailbox provider this newsletter is spam, and only the reader can undo that by subscribing again themselves.

A new subscriber answers 201. So the status says whether a subscription was created, and the body says what it now is either way.

The same person is one subscriber however their row is shaped. An address that belongs to a Commune account is attached to that account, so the subscription follows the address on it, and an address Commune has never seen is stored on the subscription itself, lowercased. Two calls differing only in case are therefore one subscriber rather than two copies of one person receiving every article twice.

source comes back commune: the subscription was made on Commune and was not mirrored off a provider's list. tags is empty, because a tag decides what somebody can read and is applied by its own call.

On a newsletter connected to an outside provider this writes Commune's record and not the provider's. Nothing is added to Kit, Mailchimp or anywhere else, so add the contact there too if that list is your source of truth. The daily sync only ever adds, so a subscriber written here is not removed by it.