Unsubscribe management
An unsubscribe that works is the cheapest deliverability investment available. Gmail and Yahoo require one-click unsubscribe for bulk senders, and a reader who cannot find the exit presses the spam button instead.
The managed header
Set "unsubscribe": true on a send and the platform adds RFC 8058 one-click
headers pointing at a hosted endpoint:
{
"from": "news@yourcompany.com",
"to": ["reader@example.com"],
"subject": "This month at Example",
"html": "<p>...</p>",
"unsubscribe": true
}
List-Unsubscribe: <https://api.lockally.com/v1/unsubscribe?t=...>
List-Unsubscribe-Post: List-Unsubscribe=One-Click
The token in the link is the authorisation: it is signed, it identifies the
workspace and the recipient, and it needs no API key. A POST from the mail
client records the suppression silently, which is what one-click means. A
GET from a human clicking shows a confirmation page first.
The result is an entry on your
suppression list with reason unsubscribe,
and every later send to that address is skipped.
What it does not do
It does not put a link in your body. The header is for the mail client’s own unsubscribe button. Providers expect a visible link in the message as well, and many readers never see the client’s button. Put one in your template.
You can use the same hosted endpoint for it, or your own preference centre.
If you run your own, record the result through
POST /v1/suppressions with reason unsubscribe, or the platform will keep
happily sending.
It does not manage preferences. One list, one state: suppressed or not. There are no topics, no frequency settings and no per-list subscriptions. If you need those, they live in your application, and the suppression list is the global off switch underneath them.
It does not apply to transactional mail, and should not. A receipt is not something to unsubscribe from. Leave the flag off for transactional sends; adding it both marks them as broadcast and invites someone to suppress themselves out of their own password resets.
Reinstating someone
Deleting the suppression is all it takes, and it should follow the person asking rather than a cleanup job:
curl -X DELETE https://api.lockally.com/v1/suppressions/reader@example.com \
-H "Authorization: Bearer $LOCKALLY_API_KEY"
Doing this in bulk, to a list of people who unsubscribed, is the fastest route to complaints and a throttled workspace.
Practical checklist
- Set
"unsubscribe": trueon every bulk send. - Put a visible unsubscribe link in the template as well.
- Honour it immediately, which the managed endpoint does for you.
- Never reinstate in bulk.
- Keep transactional mail out of it.