Unsubscribe groups
Let a recipient leave the newsletter without leaving the invoice alerts. Groups scope the unsubscribe link of a marketing message; the global list keeps working underneath.
How a group works
A group is a name in your account. A marketing message sent with unsubscribe_group: "<id>" carries an unsubscribe link and a one-click header that opt the recipient out of THAT group: the next marketing message with the same group is refused with 403, and everything else still reaches them. The unsubscribe page shows which list they left and offers to leave everything, which writes the global UNSUBSCRIBE suppression of always. Transactional email never takes a group; its unsubscribe is the global list.
Endpoints
| Endpoint | What it does |
|---|---|
| POST /email/unsubscribe-groups | Create a group: name, description, is_default (at most one default per account). Scope contacts:write. |
| GET /email/unsubscribe-groups | List every group with its opt-out count. |
| PATCH /email/unsubscribe-groups/{id} | Rename, describe or make default. |
| DELETE /email/unsubscribe-groups/{id}?confirm=true | Deletes the group AND its opt-outs. Refused with 409 without confirm when the group has opt-outs: people who left would start receiving again if you recreated it. |
| GET /email/unsubscribe-groups/{id}/optouts | The addresses that left this group, with the source: the unsubscribe link, or your API. |
| POST /email/unsubscribe-groups/{id}/optouts | Import an opt-out (bringing preferences from another provider). |
| DELETE /email/unsubscribe-groups/{id}/optouts/{optout_id} | Removes an opt-out you imported. One that came from the recipient cannot be removed. |
Migrating from SendGrid: the asm.group_id of /v3/mail/send is honored when it is the UUID of one of your groups here, and the message becomes marketing. The integer ids of the origin do not exist in this account; create the groups and use their ids.