Overview

Integration

User guide

API reference

Webhooks

Configure an inbound server

Steps

1. Create a new server in Postmark

Configuring Postmark’s Inbound API is similar to the way you may have already configured your Outbound API or SMTP servers. A single server can be created to process and track activity for each of your applications and environments. In addition, you can use the same server for both Inbound and Outbound email. 

Please note, you can only create one Inbound Stream per Server, and add only one domain to that Stream.

2. GET the server details and InboundHash

The next step is to figure out your unique InboundHash where you can forward your email. This can be found in the Inbound Stream settings page.

Inbound Email Configuration - Inbound Hash Email
Inbound Email Configuration - Inbound Hash Email

You can also get the InboundHash via the Server API.

The field InboundHash is the email mailbox we use to identify incoming email for this server. For instance, we collect any email sent to yourhash@inbound.postmarkapp.com and parse it in this server.

Example request with curl

curl "https://api.postmarkapp.com/servers/:serverid"  \
  -X GET \
  -H "Accept: application/json" \
  -H "X-Postmark-Account-Token: account token"

Example JSON response

{
  "Name": "Kermit",
  "Color": "green",
  "InboundHash": "451d9b70cf9364d6f9d51sdf34343sdf343",
  "SmtpApiActivated": false
}

3. Send to Postmark Inbound using your own email address

Depending on your use, you may not want your users to see the@inbound.postmarkapp.com address. There are two options:

  1. Use Postmark's Inbound Domain Forwarding
  2. If you do not have access to edit your DNS records, you can read our help article to learn how to configure a custom forwarding email address from your Gmail/Google Apps account.

4. Set the URL where we should POST JSON

In order for your application to receive the emails that we parse, you will need to tell Postmark where to send the JSON data for each inbound email it processes, which is done via an HTTP POST to a URL of your choice. You can set this URL in your server's settings page or using the InboundHookUrl field in the API.

To test your inbound server, we recommend using a RequestBin first.

Once emails are being sent to RequestBin successfully, your inbound server has been configured correctly and you're ready to start parsing email for your application.

Example request with curl

curl "https://api.postmarkapp.com/servers/:serverid" \
  -X PUT \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -H "X-Postmark-Account-Token: account token" \
  -d "{ 'InboundHookUrl': 'http://requestb.in/1crksas1' }"

Example JSON response

{
  "Name": "Kermit",
  "Color": "green",
  "InboundHookUrl": "http://requestb.in/1crksas1",
  "SmtpApiActivated": false
}

Securing your webhook

Many people do not want to have a public URL that anyone on the internet can hit and feed fake data in. To help with that, we support HTTP Basic authentication. You can set up your web server security and provide the credentials in the URL like the example.

Example URL

https://username:password@example.com/inboundhook