Newsletter subscribers (add-on)

Who is on the mailing list, with the lists and tags each person carries, how they joined, when they agreed and what state they are in. Search matches anywhere in an address or a name. Give campaign_id and campaign_received together to narrow the table to the people one campaign reached, or to the people it did not, which is the list a follow-up goes to. The status counts come back for the whole table rather than for the page.

One person with the whole record behind them: the consent — when they agreed, from what address, and whether the store still holds the sentence they were shown — every list they hold a membership on and its state, their tags, the import they came in with if they came in with one, the customer record they are linked to if there is one, whether the store has been told never to mail the address, and every campaign they were part of with what happened to it. This is the answer to a complaint.

Everything held about one person, as one JSON document, for answering somebody who asks what is kept about them: their profile, every list membership with its status and dates, their tags, the full consent history (each signup, confirmation, admin add or invite, import, unsubscribe and return, with the address and browser for the changes they made themselves and the note for an admin's), every message they were sent with when it was opened and each link they pressed, what the mail provider reported about them (deliveries, bounces, complaints), their automation walks, any suppression on their address, the import runs that brought them in, and any records the site adds of its own. It holds the same records deleting the person removes. Left out: the person's signing secret and address hash, and other people, including which admin made a change. Needs the same permission as the CSV export.

Add one person to a list by address, as source "admin". Say how with mode: invite sends the ordinary confirmation email and leaves them waiting on the list until they press it; subscribed adds them on your word and needs a note saying where they agreed, which goes into their consent history. Without a mode the list's own confirmation setting decides. Somebody already known keeps their standing on every other list. A suppressed, bounced or complained address is refused with a sentence saying why, and so is anybody who left that list, or every list, themselves (resubscribe_subscriber with a note is the way back for somebody who asked). The answer's outcome says added, invited, already_on or already_invited. For a list from another tool, use the CSV importer instead: it checks suppressions, counts what it did and keeps the file name as evidence.

Change somebody's name, language, lists or tags. The email address is not editable and the attempt is refused: it is the key every consent record, suppression, send row and signed link is hung off, and changing it would be creating a second person and calling it an edit. Only lists somebody already holds a membership on are moved, so this cannot put anybody on a topic they were never offered, and a list they left themselves stays left (resubscribe_subscriber, with a note, is for somebody who asked).

Take one person off every list, recorded as done by the store rather than by them. Use it when somebody has asked by email or on the phone. They can sign up again themselves whenever they like; nothing here suppresses the address.

Undo an unsubscribe, for somebody who has asked you to. Refused for an address that bounced or complained, and for one on the suppression list, because those are facts about mail the store already sent and no button in an admin overturns one — the suppression has to be removed first, on its own screen, as its own decision. This is the one way back for somebody who unsubscribed themselves, so it needs a note saying how they asked, which goes into their consent history. Name a list to put them back on that one; omit it and every list they were ever on comes back. Their other lists are left as they are.

Move a person who is waiting to confirm onto their lists, for the one whose confirmation email went to spam or never arrived and who has since asked, in writing, to be on the list. Only a pending person moves: one already on the list has nothing to confirm, one who left is a resubscribe with its own warning, and a bounced, complained or suppressed address is refused for the same reasons resubscribe refuses it. The memberships it writes are recorded as confirmed by the store, not by the person.

Remove one person from the mailing list entirely — their memberships, their tags, every send they were part of and every click they made. The suppression list is not touched, on purpose: an address that bounced last month is still an address this store must not mail, and forgetting why would be worse than keeping it. An erasure request is a different thing and arrives through the store's own customer erasure.

One action over many people: add them to a list, take them off one, add or remove a tag, unsubscribe them from everything, or delete them. Say who with exactly one of ids (up to 500), filter (the same filters list_subscribers takes, walked 500 at a time: send the answer's next back as after until finished is true) or addresses (pasted email addresses, optionally with names, for add_to_list only; new ones become subscribers). Adding to a list asks how: mode invite sends the confirmation email and leaves them pending on the list until they press it, mode subscribed adds them on your word and needs a note saying where they agreed, which goes into their consent history. Without a mode the list's own confirmation setting decides. Suppressed, bounced and complained addresses are never added, and nobody is put back on a list they left themselves. The answer counts what was done and, by reason, who was skipped. Delete removes each person the way delete_subscriber does and leaves the suppression list alone. Unsubscribe and delete over a filter need at least one filter set, or all: true to mean everybody.

Given a KahunaCart customer id, the subscriber record linked to it: their address and status, whether the store has been told never to mail them, every list they are on with how they got there, and the last campaign they were actually sent — with the date, and whether they opened it, clicked in it or it bounced. A customer with no subscriber answers with a null subscriber and empty lists rather than a 404, because most customers on most stores have never been asked. Use it to answer "is this customer on the newsletter" without paging the whole subscriber list.