Overview

Integration

User guide

API reference

Webhooks

Inbound webhook

What is an inbound webhook?

The inbound webhook is a key part of processing inbound email with Postmark. It’s described in more detail in the Process Email section, but the basic premise is that Postmark will accept and parse any emails sent to your server’s unique inbound email address (found on the “Credentials” page of your server) and any emails sent to your inbound forwarding domain. Postmark will then POST the email as JSON to the URL you specify. This allows you to build different types of applications, treating email as an incoming data source.

Set the webhook URL

The inbound webhook URL is a server setting. You can only have one inbound webhook URL per server.

Using the Postmark website

When logged into Postmark, select the server and go to the “Settings” tab and then the ”Inbound“ tab. The “Inbound Webhook” field is where you should input your webhook URL.

Using the API

You can modify the InboundHookUrl field using the Servers API to modify existing servers. You can also use the Servers API to create servers and set the InboundHookUrl field at the same time.

Inbound webhook data

An example of the full JSON document that would be POSTed to your webhook URL is to the right. A more thorough discussion of inbound processing takes place in the Parse an Email section of the documentation, but a brief description of some of the more interesting fields is below:

  • MailboxHash—this field appears in the main JSON object and also for each address the email was addressed to. If the email was sent to user+12345@example.com the MailboxHash would contain 12345. This is also know as “plus addressing”.
  • SpamAssassin headers—when we receive mail for inbound parsing, we run the emails through SpamAssassin, an open source spam filtering system. We pass that information on to you in the form of the X-Spam-Status, X-Spam-Score, and X-Spam-Tests headers and your application can decide whether or not the inbound message parsed is legitimate or not.
  • StrippedTextReply—if the inbound email was a reply to another email, Postmark may be able to strip out the information for only the reply.

Example JSON webhook data

{
  "FromName": "Postmarkapp Support",
  "From": "support@postmarkapp.com",
  "FromFull": {
    "Email": "support@postmarkapp.com",
    "Name": "Postmarkapp Support",
    "MailboxHash": ""
  },
  "To": "\"Firstname Lastname\" <yourhash+SampleHash@inbound.postmarkapp.com>",
  "ToFull": [
    {
      "Email": "yourhash+SampleHash@inbound.postmarkapp.com",
      "Name": "Firstname Lastname",
      "MailboxHash": "SampleHash"
    }
  ],
  "Cc": "\"First Cc\" <firstcc@postmarkapp.com>, secondCc@postmarkapp.com>",
  "CcFull": [
    {
      "Email": "firstcc@postmarkapp.com",
      "Name": "First Cc",
      "MailboxHash": ""
    },
    {
      "Email": "secondCc@postmarkapp.com",
      "Name": "",
      "MailboxHash": ""
    }
  ],
  "Bcc": "\"First Bcc\" <firstbcc@postmarkapp.com>, secondbcc@postmarkapp.com>",
  "BccFull": [
    {
      "Email": "firstbcc@postmarkapp.com",
      "Name": "First Bcc",
      "MailboxHash": ""
    },
    {
      "Email": "secondbcc@postmarkapp.com",
      "Name": "",
      "MailboxHash": ""
    }
  ],
  "OriginalRecipient": "yourhash+SampleHash@inbound.postmarkapp.com",
  "Subject": "Test subject",
  "MessageID": "73e6d360-66eb-11e1-8e72-a8904824019b",
  "ReplyTo": "replyto@postmarkapp.com",
  "MailboxHash": "SampleHash",
  "Date": "Fri, 1 Aug 2014 16:45:32 -04:00",
  "TextBody": "This is a test text body.",
  "HtmlBody": "<html><body><p>This is a test html body.<\/p><\/body><\/html>",
  "StrippedTextReply": "This is the reply text",
  "Tag": "TestTag",
  "Headers": [
    {
      "Name": "X-Header-Test",
      "Value": ""
    },
    {
      "Name": "X-Spam-Status",
      "Value": "No"
    },
    {
      "Name": "X-Spam-Score",
      "Value": "-0.1"
    },
    {
      "Name": "X-Spam-Tests",
      "Value": "DKIM_SIGNED,DKIM_VALID,DKIM_VALID_AU,SPF_PASS"
    }
  ],
  "Attachments": [
    {
      "Name": "test.txt",
      "Content": "VGhpcyBpcyBhdHRhY2htZW50IGNvbnRlbnRzLCBiYXNlLTY0IGVuY29kZWQu",
      "ContentType": "text/plain",
      "ContentLength": 45
    }
  ]
}

Testing 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 '{ "FromName": "Postmarkapp Support", "From": "support@postmarkapp.com", "FromFull": { "Email": "support@postmarkapp.com", "Name": "Postmarkapp Support", "MailboxHash": "" }, "To": "\"Firstname Lastname\" <yourhash+SampleHash@inbound.postmarkapp.com>", "ToFull": [ { "Email": "yourhash+SampleHash@inbound.postmarkapp.com", "Name": "Firstname Lastname", "MailboxHash": "SampleHash" } ], "Cc": "\"First Cc\" <firstcc@postmarkapp.com>, secondCc@postmarkapp.com", "CcFull": [ { "Email": "firstcc@postmarkapp.com", "Name": "First Cc", "MailboxHash": "" }, { "Email": "secondCc@postmarkapp.com", "Name": "", "MailboxHash": "" } ], "Bcc": "\"First Bcc\" <firstbcc@postmarkapp.com>, secondbcc@postmarkapp.com", "BccFull": [ { "Email": "firstbcc@postmarkapp.com", "Name": "First Bcc", "MailboxHash": "" }, { "Email": "secondbcc@postmarkapp.com", "Name": "", "MailboxHash": "" } ], "Subject": "Test subject", "MessageID": "73e6d360-66eb-11e1-8e72-a8904824019b", "ReplyTo": "replyto@postmarkapp.com", "MailboxHash": "SampleHash", "Date": "Fri, 1 Aug 2014 16:45:32 -04:00", "TextBody": "This is a test text body.", "HtmlBody": "<html><body><p>This is a test html body.<\/p><\/body><\/html>", "StrippedTextReply": "This is the reply text", "Tag": "TestTag", "Headers": [ { "Name": "X-Header-Test", "Value": "" }, { "Name": "X-Spam-Status", "Value": "No" }, { "Name": "X-Spam-Score", "Value": "-0.1" }, { "Name": "X-Spam-Tests", "Value": "DKIM_SIGNED,DKIM_VALID,DKIM_VALID_AU,SPF_PASS" } ], "Attachments": [ { "Name": "test.txt", "Content": "VGhpcyBpcyBhdHRhY2htZW50IGNvbnRlbnRzLCBiYXNlLTY0IGVuY29kZWQu", "ContentType": "text/plain", "ContentLength": 45 } ] }'

How you can use the data

By turning emails into easy to use JSON documents, you allow your users to affect your application from their email client. This opens up many areas of interactivity for your application that you may not have considered before because handling email was too difficult. You can read our sample inbound workflow for a high level walkthrough of building a comment by email system.

Errors and retries

When a URL returns a non-200 code, we will schedule the JSON POST for a retry. A total of 10 retries will be made, with growing intervals from 1 minute to 6 hours. If all of the retries have failed, your Inbound page will show the message as Inbound Error.