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 “Settings” page of your Inbound Message Stream)” 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.
Note: The format of the datetime in the Date field will be based on the format provided by the message's sending mailserver. Postmark currently does not have a way to set a default for these formats.
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 MailboxHashwould contain 12345. This is also know as “plus addressing”.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.{
"FromName": "Postmarkapp Support",
"MessageStream": "inbound",
"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
}
]
}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 '{
"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
}
]
}'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.
If Postmark does not receive a 200 response from a webhook server, we will retry the POSTing the webhooks. If we receive a 403 response, we will stop retries. A total of 10 retries will be made, with growing intervals. The retry schedule is:
The inbound webhook URL is an Inbound Message Stream setting. You can only have one inbound webhook URL per Inbound Message Stream.
When logged into Postmark, select the Server, select the Server's Inbound message Stream, and then click Settings. The Webhook field is where you should input your webhook URL.
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.