Announcing the Postmark Messages API

We’re very excited to announce the release of the Postmark Messages API! This is a set of endpoints that will allow you to retrieve copies of messages over the Postmark API. It’s been a highly requested feature and today we’re rolling it out.

Requesting Messages #

To query for messages you’ve sent, you can use the new messages endpoint:

http://api.postmarkapp.com/messages/outbound?offset=0&count=2

This example will return the two most recent outbound messages sent for the Postmark Server whose API key you indicated in the X-Postmark-Server-Token header. You may retrieve up to 500 messages per page before using the offset parameter to retrieve the next 500. Offset and count are required parameters.

Optional parameters for this query are recipient, fromemail, tag, and subject which will filter by who the message was sent to, who it was sent from, the tags used in the message, and the message subject respectively.

The query will return an array of selected parts of your messages in descending order by sent date:

Requesting the Full Message #

You may notice that some parts of the messages are not shown in the array list like the original TextBody, HtmlBody, and SMTP body. This is to keep the search filter light and fast. To retrieve the full details of a message, use the details endpoint and specify the MessageID in the url:

http://api.postmarkapp.com/messages/outbound/e9d3e7ac-4765-aee2-1b5e629cac63/details

This will return the fully populated details of the original message including the full body with headers. Note: While we include the attachment file names, we do not include the original attachment data in the messages API requests.

Coming full circle with the Bounce API and Messages API #

The Bounce API allows you to search for messages that could not be delivered or which were marked as SPAM by a recipient. You can also setup a “bounce webhook” to receive push notifications to your own API endpoint.

With the new Messages API, you can create a workflow to search for bounce notifications and then retrieve the original message via the Messages API to inspect.

1. Receive (or search for) a SPAM complaint bounce.

http://api.postmarkapp.com/bounces?count=10&offset=0&type=SpamComplaint

2. Use the MessageID to retrieve the details of the original message in order to find out what content may have caused the spam complaint.

http://api.postmarkapp.com/messages/outbound/0589e144-9516-4c93-8f75-8099cd149350/details

3. Review content from the original message.

Inbound Retrieval #

The Messages API works with inbound posted messages as well! To retrieve the details of an inbound message, simply use the MessageID and change the url to use the inbound endpoint:

http://api.postmarkapp.com/messages/inbound/eeaa4d94-e002-419d-93f3-08109cf29a25/details

The Inbound retrieval data matches the data sent to your Inbound Webhook, so in case you no longer have that data, you can always retrieve it via the Messages API.

You can find the full documentation for the new Messages API on our developer site!