# 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](/user-guide/inbound) 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](/user-guide/inbound/inbound-domain-forwarding). 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.

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](/user-guide/inbound/sample-inbound-workflow) for a high level walkthrough of building a comment by email system.

_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._

## Create a new webhook

In your Postmark account — select a Server, then its Inbound Message Stream, and open the Settings tab. Enter your URL in the Webhook field. Each Inbound Message Stream has one inbound webhook URL. You can also use the [API](/api/servers#edit-a-server).

### Using the API

Set InboundHookUrl on the server when you [create](/api/servers#create-a-server) or [edit](/api/servers#edit-a-server) a server. Whichever method you choose, send a test event with the cURL example below to confirm your endpoint accepts it before real mail starts arriving.

## Event 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](/user-guide/inbound/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”.

- SpamAssassin headers — When we receive mail for inbound parsing, we run the emails through [SpamAssassin](https://spamassassin.apache.org/), 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

```js
{
  "FromName": "Alan Turing",
  "MessageStream": "inbound",
  "From": "alanturing@computers.com",
  "FromFull": {
    "Email": "alanturing@computers.com",
    "Name": "Alan Turing",
    "MailboxHash": ""
  },
  "To": "\"Margaret Hamilton\" <yourhash+SampleHash@inbound.postmarkapp.com>",
  "ToFull": [
    {
      "Email": "yourhash+SampleHash@inbound.postmarkapp.com",
      "Name": "Margaret Hamilton",
      "MailboxHash": "SampleHash"
    }
  ],
  "Cc": "\"Katherine Johnson\" <katherine@nasa.com>, <dorothy@nasa.com>",
  "CcFull": [
    {
      "Email": "katherine@nasa.com",
      "Name": "Katherine Johnson",
      "MailboxHash": ""
    },
    {
      "Email": "dorothy@nasa.com",
      "Name": "",
      "MailboxHash": ""
    }
  ],
  "Bcc": "\"Mary Jackson\" <mary@nasa.com>",
  "BccFull": [
    {
      "Email": "mary@nasa.com",
      "Name": "Mary Jackson",
      "MailboxHash": ""
    }
  ],
  "OriginalRecipient": "yourhash+SampleHash@inbound.postmarkapp.com",
  "Subject": "Saying Hello!",
  "MessageID": "883953f4-6105-42a2-a16a-77a8eac79483",
  "ReplyTo": "alanturing@computers.com",
  "MailboxHash": "SampleHash",
  "Date": "Thu, 5 Nov 2026 16:33:54 -0500",
  "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": "welcome-email",
  "Headers": [
    {
      "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 events

If you’re developing on your local machine or don’t have a public URL for your API, the cURL request example below sends a test webhook to your service. Replace _&lt;your-webhook-url>_, run the command, and verify it accepts and processes the event as expected.

### Example cURL

```bash
curl <your-webhook-url> \
  -X POST \
  -H "Content-Type: application/json" \
  -d '{
  "FromName": "Alan Turing",
  "MessageStream": "inbound",
  "From": "alanturing@computers.com",
  "FromFull": {
    "Email": "alanturing@computers.com",
    "Name": "Alan Turing",
    "MailboxHash": ""
  },
  "To": "\"Margaret Hamilton\" <yourhash+SampleHash@inbound.postmarkapp.com>",
  "ToFull": [
    {
      "Email": "yourhash+SampleHash@inbound.postmarkapp.com",
      "Name": "Margaret Hamilton",
      "MailboxHash": "SampleHash"
    }
  ],
  "Cc": "\"Katherine Johnson\" <katherine@nasa.com>, <dorothy@nasa.com>",
  "CcFull": [
    {
      "Email": "katherine@nasa.com",
      "Name": "Katherine Johnson",
      "MailboxHash": ""
    },
    {
      "Email": "dorothy@nasa.com",
      "Name": "",
      "MailboxHash": ""
    }
  ],
  "Bcc": "\"Mary Jackson\" <mary@nasa.com>",
  "BccFull": [
    {
      "Email": "mary@nasa.com",
      "Name": "Mary Jackson",
      "MailboxHash": ""
    }
  ],
  "OriginalRecipient": "yourhash+SampleHash@inbound.postmarkapp.com",
  "Subject": "Saying Hello!",
  "MessageID": "883953f4-6105-42a2-a16a-77a8eac79483",
  "ReplyTo": "alanturing@computers.com",
  "MailboxHash": "SampleHash",
  "Date": "Thu, 5 Nov 2026 16:33:54 -0500",
  "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": "welcome-email",
  "Headers": [
    {
      "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
    }
  ]
}'
```

## Errors and retries

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:

- 1 Min

- 5 mins

- 10 mins (x 3)

- 15 mins

- 30 mins

- 1 hour

- 2 hours

- 6 hours

If all of the retries have failed, your Inbound page will show the message as Inbound Error. If need be, you can [retry a failed inbound message for processing](/api/messages).
