Overview

Integration

User guide

API reference

Webhooks

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.

Set the spam complaint webhook URL #

The spam complaint webhook URL is a server setting. You can only have one delivery webhook URL per server. You can enable the webhook in the following ways:

Using the Postmark website

When logged into Postmark, select the server and go to the webhooks” tab. Click Add webhook” and input your webhook URL in the Webhook URL” field and then select the Spam complaint” checkbox. 

Using the API

Currently, it's not possible to set up modular webhooks with the public API. We have plans to update this in the future, but for now, modular webhooks can only be set up in the UI.

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 email was delivered.
  • Subject—Subject line of the email that was sent
  • Metadata—custom metadata that was included in the email.

Example JSON webhook data

{
  "RecordType": "SpamComplaint",
  "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": "2018-02-20T12:54:23.3396434-05:00",
  "DumpAvailable": true,
  "Inactive": true,
  "CanActivate": false,
  "Subject": "Test subject"
}

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.