Unsubscribe links

Gmail, Yahoo and other providers show an Unsubscribe button next to the sender when an email has a working one-click unsubscribe header (RFC 8058). If people cannot unsubscribe easily, they report the email as spam instead. We add the header for you.

The headers we add#

List-Unsubscribe: <https://securessmtp.com/api/v1/u/<token>>
List-Unsubscribe-Post: List-Unsubscribe=One-Click

We add them when both of these are true:

• The email has exactly one recipient in total (to, cc and bcc together).
• You did not send your own List-Unsubscribe header (in headers for the API, or in the message for SMTP).

The token is signed and holds the recipient’s address and your site. It can only unsubscribe that one address from that one site.

What happens when someone unsubscribes#

• One-click button in the mail app. The mail provider sends a POST to the link and the unsubscribe is recorded at once.
• Link opened in a browser. A page asks the person to confirm with an Unsubscribe button. Only the button records it, so link scanners and previews do not unsubscribe anyone.

From then on, emails from that site to that address are skipped:

• The address is removed from to; the email still goes to any other recipients.
• If nobody is left, nothing is sent. The API answers HTTP 200 with ok: false, reason: "send_failed" and error: "all_recipients_unsubscribed". Over SMTP the reply is 550 5.7.1.
• Your other sites can still send to the address.
• Addresses in cc and bcc are not checked.

Unsubscribes are not shown in the dashboard and cannot be undone there. If someone unsubscribed by mistake, contact support.

Visible unsubscribe link#

POST /mail/send does not add a visible unsubscribe link to the body. For newsletters and other marketing mail, put your own link in the body as well: Gmail and Yahoo expect both the header and a visible link in bulk marketing mail.

Follow-up sequences are different: each step gets a short footer (“Don’t want these emails? Unsubscribe”) unless the step’s template already places the link with {{unsubscribe_url}}.

Using your own unsubscribe system#

If you send your own List-Unsubscribe header, we keep it and do not add ours. Unsubscribe requests then go to you, and our per-site list does not know about them: you must stop sending to those people yourself. Include List-Unsubscribe-Post: List-Unsubscribe=One-Click too if your link supports one-click POST requests.

{
  "to": "[email protected]",
  "subject": "October newsletter",
  "html": "<p>…</p><p><a href=\"https://example.com/unsubscribe?u=8f3a\">Unsubscribe</a></p>",
  "headers": {
    "List-Unsubscribe": "<https://example.com/unsubscribe?u=8f3a>",
    "List-Unsubscribe-Post": "List-Unsubscribe=One-Click"
  }
}