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.

Set the subscription change webhook URL #

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.

Subscription change webhook 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.

Example JSON webhook data

{  
  "RecordType":"SubscriptionChange",
  "MessageID": "883953f4-6105-42a2-a16a-77a8eac79483",
  "ServerID":123456,
  "MessageStream": "outbound",
  "ChangedAt": "2020-02-01T10:53:34.416071Z",
  "Recipient": "bounced-address@wildbit.com",
  "Origin": "Recipient",
  "SuppressSending": true,
  "SuppressionReason": "HardBounce",
  "Tag": "my-tag",
  "Metadata": {
    "example": "value",
    "example_2": "value"
  }
}

Testing the subscription change webhook with curl #

If you’re developing on your local machine or don’t have a public URL for your API, the curl request to the right has an example webhook POST request. Replace with the API route that you want to use for your webhook URL. The curl request will allow you to verify that your webhook URL is able to accept requests with the same JSON format that the Postmark servers will use.

Example curl call

curl <your-url> \
  -X POST \
  -H "Content-Type: application/json" \
  -d '{
  "RecordType": "SubscriptionChange",
  "MessageID": "883953f4-6105-42a2-a16a-77a8eac79483",
  "ServerID": 4509041,
  "MessageStream": "outbound",
  "ChangedAt": "2020-02-01T10:53:34.416071Z",
  "Recipient": "hard-bounce@wildbit.com",
  "Origin": "Customer",
  "SuppressSending": true,
  "SuppressionReason": "HardBounce",
  "Tag": "my-tag",
  "Metadata": {
    "example": "value",
    "example_2": "value"
  }
}'

How you can use the subscription change data #

There are many possible uses for the data provided by using the subscription change webhook:

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.