Subscription change webhook

What is a subscription change? #

A subscription change is recorded when an email address is added or removed from a Message Stream's Suppression list. An email address is added to a Suppression List after a Hard Bounce, Spam Complaint, Unsubscribe, or Manual Suppression. A manual suppression is created in Postmark's UI or using the API. 

An email address is removed from the suppression list manually by choosing an address to reactivate in Postmark's UI or using the API.

You can also get the suppression list using the API.

Note: The datetime for the ChangedAt field is in ISO 8601 format.

What can I use subscription change events for?

• Use the webhook in place of the bounce and spam complaints webhook to receive notifications on inactive addresses.
• Maintain a suppression list of your own.
• Notify a user in your app their address is currently active/inactive.

Create a new webhook #

Using the Postmark website

When logged into Postmark, select the Server, the Message Stream, and then go to the Webhooks tab. Choose Add webhook and input your webhook URL in Webhook URL and then select the Subscription Change checkbox.

Using the API

You can modify the SubscriptionChange field using the Webhooks API to edit an existing Webhook. You can also use the Webhooks API to create webhooks and set the SubscriptionChange field at the same time. After setting the URL, verify the webhook so you know it's reachable before events start flowing. See Verifying your webhook.
 

Event data #

An example of the full JSON document that would be POSTed to your webhook URL is to the right.

• The SuppressSending field will inform whether that was a deactivation or reactivation.
• MessageID is null for Manual Suppressions with Origin value of Customer or Admin and Reactivations.
• Possible SuppressionReason values are: HardBounce, SpamComplaint, or ManualSuppression.
• If a recipient unsubscribes, they will be suppressed with the SuppressionReason of ManualSuppression.
• The SuppressionReason and Tag fields are null, while the Metadata field is an empty object when SuppressSending = false (reactivation).
• The Origin field shows where that originated from. e.g.: Recipient, Customer, Admin
• ChangedAt—timestamp of when the subscription changed.

Testing events #

If you’re developing on your local machine or don’t have a public URL for your API, the cURL request example below sends a test webhook to your service. Replace <your-webhook-url>, run the command, and verify it accepts and processes the event as expected.