Grow with us: Join Postmark's new referral partner program and start earning
Learn more
x
Webhook notifications

Get notified about important message events with Webhooks.

Use webhooks to notify users about email delivery issues, or find out when a customer opens an important email.

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": "john@example.com",
    "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": "john@example.com",
    "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": "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",
    "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": "john@example.com",
    "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": "john@example.com",
    "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.

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: 'sender@example.com',
    to: 'john@example.com',
    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": "john@example.com",
    "DeliveredAt": "2014-08-01T13:28:10.2735393-04:00",
    "Details": "Test delivery webhook details",
    "Metadata": {
      "user_id": 43
    }
  }

Still have questions?

  • Anna Ward Anna
  • Ignacio Roig Ignacio

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

Contact us