Skip to main content
RFC 8058 is the inbox “leave” button, no need to open the email and hunt for the footer.

​
Why use it?

Gmail and Yahoo require one-click unsubscribe for promotional mail. Without the right headers, opt-out depends only on the HTML link (preference center). With RFC 8058, the mailbox shows a native button and Notifique honors the request immediately.

​
When to use it

  • MARKETING template (and campaigns/automations using it) → RFC 8058 headers by default
  • POST /v1/email/messages when the recipient maps to a contact → by default
  • Transactional email (receipt, OTP, password reset) → set listUnsubscribe: false
  • Recipient has no contact in the workspace → headers are not injected (no token)

​
How it works

  1. On send, Notifique issues a token (same family as {{preferences_link}}) and sets MIME headers:
    • List-Unsubscribe: <https://…/w/list-unsubscribe/:contactId?token=…>
    • List-Unsubscribe-Post: List-Unsubscribe=One-Click
  2. Gmail/Yahoo POST to that URL with body List-Unsubscribe=One-Click (no cookies, no login), opt-out happens only on POST.
  3. A GET to the same URL only validates the token and shows a confirmation page (no preference change, avoids scanners/prefetch).
  4. On POST, Notifique unsubscribes immediately:
    • with topic in the URL (template with a topic) → topic UNSUBSCRIBED (invalid topic → error, no global fallback)
    • without topic → receiveMarketing = false
  5. The success page may link to the preference center to resubscribe.
The footer with {{preferences_link}} / “click here to unsubscribe” still exists. RFC 8058 is additive (headers); it does not replace the preference center.

​
Direct API (POST /v1/email/messages)

If listUnsubscribeTopicId does not exist in this workspace: 400 with code INVALID_LIST_UNSUBSCRIBE_TOPIC. See Error responses. For transactional mail:

​
Next steps