The Click webhook is a way for Postmark to notify your application that a unique recipient clicked a tracked link in your email. This can be useful in a variety of situations, such determining effectiveness of your transactional email (can customers easily identify a reset-password link? Do they like to view order confirmations in their account dashboard? Or, simply for auditing purposes.
You may also use the Messages API to pull data about click events, but with the click webhook Postmark pushes your click events as they happen. A click webhook will push data to your application in easily parsable JSON format.
Postmark will POST one event per unique click to your webhook for clicks in links to messages sent within your retention period (which is 45 days by default, but the data retention period can be customized from 7 to 365 days). Postmark cannot determine the uniqueness of a click after your retention period expires, and therefore will not post an event to your webhook for clicks in messages older than your retention period.
A click is considered unique if the recipient has never clicked a particular link within a message within the retention period of when it was sent.
For example:
You send a single email with a tracked link to Sally and Bob. Both of them click the link. Your server will receive two calls with unique webhook payloads. However, if either Sally or Bob clicks the link again, your server will not receive an additional event. Additionally, if your email includes multiple links, each unique link clicked by a recipient will register a new click, and trigger another call to your webhook with information about which link was clicked, by which recipient.
For links that are older than your retention period, we will still make sure they are redirected to the original url, but they will not be considered unique, so no will be posted in this case.
Note: The datetime for the ReceivedAt field will be in ISO 8601 format.
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 Link Click checkbox.
You can modify the Click field using the Webhooks API to edit an existing Webhook. You can also use the Webhooks API to create webhooks and set the Click field at the same time.
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:
Recipient—the email address of the recipient that clicked the link.Tag—delivery tag that was used when the message was sent.Metadata—custom metadata that was included in the email.OriginalLink—the link that the recipient clicked within the email.ClickLocation—whether the link was clicked from HTML or Text.ReceivedAt—the timestamp of when the link was clicked.{
"RecordType": "Click",
"MessageStream": "outbound",
"ClickLocation": "HTML",
"Client": {
"Name": "Chrome 35.0.1916.153",
"Company": "Google",
"Family": "Chrome"
},
"OS": {
"Name": "OS X 10.7 Lion",
"Company": "Apple Computer, Inc.",
"Family": "OS X 10"
},
"Platform": "Desktop",
"UserAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_7_5) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/35.0.1916.153 Safari/537.36",
"OriginalLink": "https://example.com",
"Geo": {
"CountryISOCode": "RS",
"Country": "Serbia",
"RegionISOCode": "VO",
"Region": "Autonomna Pokrajina Vojvodina",
"City": "Novi Sad",
"Zip": "21000",
"Coords": "45.2517,19.8369",
"IP": "8.8.8.8"
},
"MessageID": "00000000-0000-0000-0000-000000000000",
"Metadata" : {
"a_key" : "a_value",
"b_key": "b_value"
},
"ReceivedAt": "2017-10-25T15:21:11.9065619Z",
"Tag": "welcome-email",
"Recipient": "john@example.com"
}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.
curl <your-url> \
-X POST \
-H 'Content-Type: application/json' \
-d '{
"ClickLocation": "HTML",
"Client": {
"Name": "Chrome 35.0.1916.153",
"Company": "Google",
"Family": "Chrome"
},
"OS": {
"Name": "OS X 10.7 Lion",
"Company": "Apple Computer, Inc.","Family": "OS X 10"
},
"Platform": "Desktop",
"UserAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_7_5) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/35.0.1916.153 Safari/537.36",
"OriginalLink": "https://example.com",
"Geo": {
"CountryISOCode": "RS",
"Country": "Serbia",
"RegionISOCode": "VO",
"Region": "Autonomna Pokrajina Vojvodina",
"City": "Novi Sad",
"Zip": "21000",
"Coords": "45.2517,19.8369",
"IP": "127.0.0.1"
},
"MessageID": "00000000-0000-0000-0000-000000000000",
"ReceivedAt": "2017-10-25T15:21:11.9065619Z",
"Tag": "welcome-email",
"Recipient": "john@example.com",
"RecordType": "Click"
}'There are many possible uses for the data provided by using the click webhook: