Spam complaint webhook

What is a spam complaint? #

A spam complaint is recorded when a user clicks This is Spam or Mark as Spam from email clients like Yahoo, Hotmail, AOL, etc... from their inbox. While you should not have any spam complaints, they do happen. Once a spam complaint is recorded, Postmark will deactivate this address and will not let you reactivate it.

In the email industry, spam complaints are a clear metric to determine abuse and poor sending practices. It’s important that we take these reports seriously to ensure the best delivery for all customers. If you feel a spam complaint has a reason for being reactivated, please contact Postmark support directly.

Note: The datetime for the BouncedAt field will be in ISO 8601 format.

Set the spam complaint webhook URL #

Using the Postmark website

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

Using the API

You can modify the SpamComplaint field using the Webhooks API to edit an existing Webhook. You can also use the Webhooks API to create webhooks and set the SpamComplaint field at the same time.

Spam complaint webhook data #

An example of the full JSON document that would be POSTed to your webhook URL is to the right. A brief description of some of the more interesting fields is below:

Email—the email address of the recipient.
Tag—delivery tag that was used when the message was sent
BouncedAt—timestamp of when complaint occurred.
Subject—Subject line of the email that was sent
Metadata—custom metadata that was included in the email.

Example JSON webhook data

{
  "RecordType": "SpamComplaint",
  "MessageStream": "outbound",
  "ID": 42,
  "Type": "SpamComplaint",
  "TypeCode": 512,
  "Name": "Spam complaint",
  "Tag": "Test",
  "MessageID": "00000000-0000-0000-0000-000000000000",
  "Metadata" : {
    "a_key" : "a_value",
    "b_key": "b_value"
   },
  "ServerID": 1234,
  "Description": "",
  "Details": "Test spam complaint details",
  "Email": "john@example.com",
  "From": "sender@example.com",
  "BouncedAt": "2019-11-05T16:33:54.9070259Z",
  "DumpAvailable": true,
  "Inactive": true,
  "CanActivate": false,
  "Subject": "Test subject",
  "Content": "<Abuse report dump>"
}

Testing the spam complaint 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 <your-url> 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 '{
  "ID": 42,
  "Type": "SpamComplaint",
  "TypeCode": 512,
  "Name": "Spam complaint",
  "Tag": "Test",
  "MessageID": "00000000-0000-0000-0000-000000000000",
  "ServerID": 1234,
  "Description": "",
  "Details": "Test spam complaint details",
  "Email": "john@example.com",
  "From": "sender@example.com",
  "BouncedAt": "2018-02-20T12:54:23.3396434-05:00",
  "DumpAvailable": true,
  "Inactive": true,
  "CanActivate": false,
  "Subject": "Test subject"
}'

How you can use the spam complaint data #

There are many possible uses for the data provided by using the spam complaint webhook:

You get instantly informed that a particular email has been explicitly marked as spam and you can initiate further action based on that event.
You could use the data to generate statistics that are specific to your application.
You could use the data to provide your users with an UI enabling them to see what happened with their email notifications.