# Spam complaint webhook

## What is a spam complaint webhook?

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](mailto:support@postmarkapp.com) directly.

### What can I do with spam complaint events?

- Instantly informed that a particular email has been explicitly marked as spam and you can initiate further action based on that event.

- Generate statistics that are specific to your application.

- Provide your users with an UI enabling them to see what happened with their email notifications.

## Create a new webhook

In your Postmark account — select a Server, Message Stream, and navigate to the Webhooks settings tab. Add a new webhook with your URL and toggle the Spam Complaint type. You can also use the [API](/api/webhooks#create-a-webhook).

**Using the API**

Set _Triggers.SpamComplaint.Enabled_ to _true_ to enable this event type when you [create](/api/webhooks#create-a-webhook) or [edit](/api/webhooks#edit-a-webhook) webhooks. Whichever method you choose, [verify](/webhooks/webhooks-overview#verifying-your-webhook) everything works as expected before real events start flowing.

## Event 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 (ISO 8601 format).

- **Subject** — Subject line of the email that was sent.

- **Metadata** — Custom metadata that was included in the email.

### Example JSON webhook data

```js
{
  "RecordType": "SpamComplaint",
  "MessageStream": "outbound",
  "ID": 692560174,
  "Type": "SpamComplaint",
  "TypeCode": 100001,
  "Name": "Spam complaint",
  "Tag": "welcome-email",
  "MessageID": "883953f4-6105-42a2-a16a-77a8eac79483",
  "Metadata": {
    "PropA": "some value",
    "PropB": "some value"
  },
  "ServerID": 23,
  "Description": "The subscriber explicitly marked this message as spam.",
  "Details": "Test spam complaint details",
  "Email": "margareth@nasa.com",
  "From": "alanturing@computers.com",
  "BouncedAt": "2026-11-05T16:33:54.9070259Z",
  "DumpAvailable": true,
  "Inactive": true,
  "CanActivate": false,
  "Subject": "Saying Hello!",
  "Content": "<Abuse report dump>"
}
```

## 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 _&lt;your-webhook-url>_, run the command, and verify it accepts and processes the event as expected.

### Example cURL

```bash
curl <your-webhook-url> \
  -X POST \
  -H "Content-Type: application/json" \
  -d '{
  "RecordType": "SpamComplaint",
  "MessageStream": "outbound",
  "ID": 692560174,
  "Type": "SpamComplaint",
  "TypeCode": 100001,
  "Name": "Spam complaint",
  "Tag": "welcome-email",
  "MessageID": "883953f4-6105-42a2-a16a-77a8eac79483",
  "Metadata": {
    "PropA": "some value",
    "PropB": "some value"
  },
  "ServerID": 23,
  "Description": "The subscriber explicitly marked this message as spam.",
  "Details": "Test spam complaint details",
  "Email": "margareth@nasa.com",
  "From": "alanturing@computers.com",
  "BouncedAt": "2026-11-05T16:33:54.9070259Z",
  "DumpAvailable": true,
  "Inactive": true,
  "CanActivate": false,
  "Subject": "Saying Hello!",
  "Content": "<Abuse report dump>"
}'
```
