C C-Connect Documentation
Português English

Unsubscribing

The headers marketing requires, what Gmail and Outlook demand, and why we refuse rather than fix.

A marketing message has to carry a way to unsubscribe, and a link in the footer is not enough.

The two headers

We write them from the unsubscribe_url you send:

List-Unsubscribe: <https://company.com/unsubscribe/abc123>
List-Unsubscribe-Post: List-Unsubscribe=One-Click

The first tells the mail client where unsubscribing happens. The second says a single POST carries it out, with no screens in between.

That is what puts the Unsubscribe button next to the sender in Gmail and Outlook, before the person opens the message. Since February 2024 both require the two headers from anybody sending volume, and a list without them watches its delivery rate fall with no error message anywhere.

What your endpoint has to do

Accept a POST with no useful body at the URL you gave, and unsubscribe the person that URL belongs to.

  • The URL has to identify the person by itself. An opaque per recipient token is the way; one link shared by everybody unsubscribes nobody.
  • Do not ask for confirmation. The header promises one click, and an "are you sure?" screen makes the mail client report the operation as failed.
  • Answer 200 quickly. What you do afterwards is your own business.
  • Accept GET on the same URL too, for whoever clicks the link in the footer.

Why we refuse rather than fix

A marketing message with no unsubscribe_url is refused with 422 and does not go out.

We could generate a link of our own, and we do not. Unsubscribing has to happen in your database: if we only recorded it on our side, the person would still be on your list, would still get the next campaign, and neither you nor they would understand why.

What we do is the step after: when somebody unsubscribes and the event reaches us through the receiver's feedback, the address goes onto this account's suppression list and stops being contacted from here, even if it stays on your list by mistake.

Still worth having. The button at the top is what the mail client shows; the link in the footer is what a person looks for once they have opened the message. You can use the same URL for both.

Transactional carries none of this

A receipt has no unsubscribe, and should not. The person did not subscribe to anything: they bought something, and the receipt is part of the purchase. Putting a cancel button on it invites somebody to switch off the messages they need, and it is one of the reasons the two streams are kept apart.