How can I customize the `List-Unsubscribe` header to manage topic-specific unsubscribes?

By default, when a user clicks the native unsubscribe button in their email client (which uses the List-Unsubscribe header), they are unsubscribed from all communications within your Pushwoosh application.

To handle unsubscribes for specific topics or mailing lists, you can override this default behavior by providing a custom URL for the List-Unsubscribe header when sending an email via the API.

Solution

When using the /createEmailMessage API method, include the optional list_unsubscribe parameter and set its value to your own endpoint. That endpoint receives the unsubscribe request, so you can process it with your own logic (for example, removing the user from one specific list).

To pass user-specific information to your endpoint, use Dynamic Content placeholders inside the URL. This lets you include the user's email address (hwid), the application code, or any Custom Tag value from their profile.

Example:

Here is how to structure the list_unsubscribe parameter in your API request. This URL passes the user's email address (as hwid) and a security token stored in a Custom Tag named SecurityToken.

"list_unsubscribe": "https://app.example.com/unsubscribe?email={hwid|regular|}&token={SecurityToken|regular|}"

When the email is sent, Pushwoosh replaces the placeholders with the actual values for each recipient, creating a unique unsubscribe link.

Important Note: we strongly advise against removing the List-Unsubscribe header from your emails altogether. It is a crucial tool for maintaining sender reputation, reducing spam complaints, and staying compliant with email best practices — and your custom endpoint must genuinely honour the request.