Webhooks

Fine-grained control with modular webhooks.

Postmark’s webhooks notify your application about key message events such as bounces, deliveries, opens, clicks, and spam complaints. Each request contains a JSON object with information about the event.

You have detailed control over which message events get sent to each of your webhook URLs. Add up to 10 different URLs and secure them using HTTP Auth.

Screenshot of the page to add a new modular webhook

Bounce Webhook

Prompt a user to update their email address if an email you sent them bounced.

{
    "ID": 42,
    "Type": "HardBounce",
    "TypeCode": 1,
    "Name": "Hard bounce",
    "Tag": "Test",
    "MessageID": "883953f4-6105-42a2-a16a-77a8eac79483",
    "Description": "The server was unable to deliver your message (ex: unknown user, mailbox not found).",
    "Details": "Test bounce details",
    "Email": "[email protected]",
    "BouncedAt": "2014-08-01T13:28:10.2735393-04:00",
    "DumpAvailable": true,
    "Inactive": true,
    "CanActivate": true,
    "Subject": "Test subject",
    "Metadata": {
      "user_id": 43
    }
  }

Delivery Webhook

Check that a welcome email or invoice reached your customer.

{
    "ServerId": 23,
    "MessageID": "883953f4-6105-42a2-a16a-77a8eac79483",
    "Recipient": "[email protected]",
    "Tag": "welcome-email",
    "DeliveredAt": "2014-08-01T13:28:10.2735393-04:00",
    "Details": "Test delivery webhook details",
    "Metadata": {
      "user_id": 43
    }
  }

Spam Compliant Webhook

Take action when a user marks an email you sent as spam.

{
    "RecordType": "SpamComplaint",
    "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": "[email protected]",
    "From": "[email protected]",
    "BouncedAt": "2018-02-20T12:54:23.3396434-05:00",
    "DumpAvailable": true,
    "Inactive": true,
    "CanActivate": false,
    "Subject": "Test subject",
    "Metadata" : {
      "a_key" : "a_value",
      "b_key": "b_value"
    }
  }

Open Tracking Webhook

Identify users who aren’t looking at your emails.

{
    "FirstOpen": true,
    "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": "WebMail",
    "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",
    "Geo": {
      "CountryISOCode": "RS",
      "Country": "Serbia",
      "RegionISOCode": "VO",
      "Region": "Autonomna Pokrajina Vojvodina",
      "City": "Novi Sad",
      "Zip": "21000",
      "Coords": "45.2517,19.8369",
      "IP": "188.2.95.4"
    },
    "MessageID": "883953f4-6105-42a2-a16a-77a8eac79483",
    "ReceivedAt": "2014-06-01T12:00:00",
    "Tag": "welcome-email",
    "Recipient": "[email protected]",
    "Metadata": {
      "user_id": 43
    }
  }

Click Tracking Webhook

Find out which links users engage with most in your emails.

{
    "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",
    "ReceivedAt": "2017-10-25T15:21:11.9065619Z",
    "Tag": "welcome-email",
    "Recipient": "[email protected]",
    "Metadata": {
      "user_id": 43
    }
  }

In general, Yapmo doesn’t outsource development needs — it’s our preference to build internally. Postmark is the only exception to this rule. The reason for this is simple: Postmark is reliable, cost effective, and gets the job done. They’re best at what they do, and it lets us spend our time on our core business.

Claire Schlafly VP of Operations

Read the story

Use custom metadata to identify messages.

Let’s say you’d like to update users in real-time on the delivery status of invoice emails they’ve sent. The best way to do this would be to attach a unique User ID and Invoice Number to each email. With Postmark, you can do just that.

Easily identify messages in your application with custom metadata. This information is included in the webhook JSON, allowing you to track messages through their entire lifecycle.

API call to send a message with metadata:

client = Postmark::ApiClient.new('server token')

  client.deliver(
    from: '[email protected]',
    to: '[email protected]',
    subject: 'Webhook example',
    html_body: '<strong>Hello from Postmark!<strong>',
    metadata: {
      user_id: 43
    }
  )

Delivery webhook received by your application:

{
    "ServerId": 23,
    "MessageID": "883953f4-6105-42a2-a16a-77a8eac79483",
    "Recipient": "[email protected]",
    "DeliveredAt": "2014-08-01T13:28:10.2735393-04:00",
    "Details": "Test delivery webhook details",
    "Metadata": {
      "user_id": 43
    }
  }

Still have questions?

Anna
Ignacio

Ask us anything! We’re eager to help you with any problem or question you have…