Overview
Integration
User guide
API reference
Webhooks
Introduction
Official libraries
- Rails gem
- Ruby gem
- .NET
- Java
- PHP
- Craft plugin
- Node.js
- CLI
- WordPress plugin
- Grunt plugin
- Zapier Actions
Community libraries
- Classic ASP
- Clojure
- ColdFusion
- Django
- Drupal module
- Elixir
- Erlang
- Google Go
- Grails plugin
- Haskell
- Java
- Laravel
- Magento extension
- Node.js
- Objective-C
- Perl
- Pharo Smalltalk
- PHP 5
- PowerShell Snap-in
- Python
- Scala
- Swift
- WordPress
- Zend
Tools and Integrations
Sending email with API
- Send a single email
- Send batch emails
Sending email with SMTP
Processing email
- Configure an inbound server
- Inbound domain forwarding
- Parse an email
- Configure inbound blocking
- Sample inbound workflow
Tracking opens
- Tracking opens per Server
- Tracking opens per email
- Message opens API
Tracking links
Managing your account
- Managing sender signatures
- Managing servers
Sandbox mode
- Server sandbox mode
- Generate fake bounces
Overview
- Endpoint URL
- Authentication
- HTTP response codes
- API error codes
Email
- Send a single email
- Send batch emails
Bounce
- Get delivery stats
- Get bounces
- Get a single bounce
- Get bounce dump
- Activate a bounce
- Bounce types
- Rebound
Templates
- Send email with template
- Send batch with templates
- Push templates to another server
- Get a template
- Create a template
- Edit a template
- List templates
- Delete a template
- Validate a template
Server
- Get the server
- Edit the server
Servers
- Get a server
- Create a server
- Edit a server
- List servers
- Delete a server
Message Streams
- List message streams
- Get a message stream
- Edit a message stream
- Create a message stream
- Archive a message stream
- Unarchive a message stream
Messages
- Outbound message search
- Outbound message details
- Outbound message dump
- Inbound message search
- Inbound message details
- Bypass rules for a blocked inbound message
- Retry a failed inbound message for processing
- Message opens
- Opens for a single message
- Message clicks
- Clicks for a single message
Domains
- List domains
- Get domain details
- Create domain
- Edit domain
- Delete domain
- Verify DKIM
- Verify Return-Path
- Verify an SPF record
- Rotate DKIM keys
Sender signatures
- List sender signatures
- Get sender signature
- Create a signature
- Edit a signature
- Delete a signature
- Resend a confirmation
- Verify an SPF record
- Request a new DKIM
Stats
- Get outbound overview
- Get sent counts
- Get bounce counts
- Get spam complaints
- Get tracked email counts
- Get email open counts
- Get email platform usage
- Get email client usage
- Get click counts
- Get browser usage
- Get browser platform usage
- Get click location
Triggers: Inbound rules
- List inbound rule triggers
- Create an inbound rule trigger
- Delete a single trigger
Webhooks
- List webhooks
- Get a webhook
- Create a webhook
- Edit a webhook
- Delete a webhook
Suppressions
- Suppression dump
- Create a Suppression
- Delete a Suppression
Data Removal
- Create a Data Removal request
- Check a Data Removal request status
Webhooks overview
- What is a webhook?
- Protecting your webhook
- Testing your webhook
- Retry attempts
Bounce webhook
- What is a bounce webhook?
- Set the webhook URL
- Bounce webhook data
- Testing with curl
- How you can use the data
- Rebound
Inbound webhook
- What is an inbound webhook?
- Inbound webhook data
- Testing with curl
- How you can use the data
- Errors and retries
- Set the webhook URL
Open tracking webhook
- What is an open webhook?
- Set the webhook URL
- Open webhook data
- Testing with curl
- How you can use the data
Delivery webhook
- What is a delivery webhook?
- Set the webhook URL
- Delivery webhook data
- Testing with curl
- How you can use the data
Click webhook
- What is a click webhook?
- Set the webhook URL
- Click webhook data
- Testing with curl
- How you can use the data
Spam complaint webhook
- What is a spam complaint?
- Set the webhook URL
- Spam complaint webhook data
- Testing the spam complaint webhook with curl
- How you can use the data
Subscription change webhook
- What is a subscription change?
- Set the subscription change webhook URL
- Subscription change webhook data
- Testing the subscription change webhook with curl
- How you can use the subscription change data
SMTP API Error
- What is an SMTP API Error
- Set SMTP API Errors for a Server
- SMTP API Error Data
- Testing the SMTP API Error
- How can you use SMTP API Error
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 sentBouncedAt
—timestamp of when complaint occurred.Subject
—Subject line of the email that was sentMetadata
—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.