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 list_unsubscribe parameter and set its value to your custom URL endpoint. This endpoint will receive the unsubscribe request, allowing you to process it with your own logic (e.g., removing a user from a specific list).

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

Example:

Here is an example of 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 will replace the placeholders with the actual values for each recipient, creating a unique unsubscribe link.

Important Note: We strongly advise against completely removing the List-Unsubscribe header from your emails. This header is a crucial tool for maintaining a good sender reputation, reducing spam complaints, and ensuring compliance with email best practices.