Postmark
Postmark API

Messages

Search and inspect sent and received messages, and query open and click events.


GET
https://api.postmarkapp.com
/messages/inbound

Searches messages received through the server's inbound stream. A search can return up to 10,000 messages; use fromdate and todate to retrieve larger sets.

Inbound message search › query Parameters

count
​integer · min: 1 · max: 500 · required

Number of records to return per request. Max 500. count + offset cannot exceed 10,000.

offset
​integer · min: 0 · required

Number of records to skip. count + offset cannot exceed 10,000.

recipient
​string

Filter by the recipient of the email.

fromemail
​string

Filter by the sender email address.

tag
​string

Filter by tag.

subject
​string

Filter by email subject.

mailboxhash
​string

Filter by mailbox hash.

status
​string · enum

Filter by status. Defaults to processed, so only processed messages are returned unless you ask otherwise.

Enum values:
blocked
processed
queued
failed
scheduled
Default: processed
todate
​string

Return records up to this date/time (inclusive), e.g. 2026-01-31T12:00:00. Postmark uses US Eastern Time.

fromdate
​string

Return records starting from this date/time (inclusive), e.g. 2026-01-01T12:00:00. Postmark uses US Eastern Time.

Inbound message search › Responses

A page of inbound messages.

Paged list of inbound messages.
TotalCount
​integer · required

Number of messages matching the search.

Example: 7
​InboundMessageSummary[] · required

Messages for the requested page.

Example: [{"From":"dart-zzzzz@example.com","FromName":"Dart Zzzzz","FromFull":{"Email":"dart-zzzzz@example.com","Name":"Dart Zzzzz","MailboxHash":""},"To":"ad8a4d0842c486355a33a7f019caab51@inbound.postmarkapp.com","ToFull":[{"Email":"dart-zzzzz@example.com","Name":"Dart Zzzzz","MailboxHash":""}],"Cc":"","CcFull":[{"Email":"dart-zzzzz@example.com","Name":"Dart Zzzzz","MailboxHash":""}],"ReplyTo":"","OriginalRecipient":"ad8a4d0842c486355a33a7f019caab51@inbound.postmarkapp.com","Subject":"Test","Date":"Thu, 13 Feb 2014 17:48:22 +0300","MailboxHash":"","Tag":"","Attachments":[{"Name":"myimage.png","ContentID":"myimage.png@01CE7342.75E71F80","ContentType":"image/png","ContentLength":4096}],"MessageID":"cc5727a0-ea30-4e79-baea-aa43c9628ac4","Status":"Processed"}]

Bypass rules for a blocked inbound message

PUT
https://api.postmarkapp.com
/messages/inbound/{messageId}/bypass

Releases an inbound message that was blocked by an inbound rule so that it is processed normally.

Bypass rules for a blocked inbound message › path Parameters

messageId
​string · uuid · required

Unique ID of the message (MessageID returned when sending).

Bypass rules for a blocked inbound message › Responses

The message was released.

Generic response returned by operations that only report a result code and message.
ErrorCode
​integer · required

Postmark API error code. 0 means the request succeeded. See the API error code table in the API description.

Example: 0
Message
​string · required

Human-readable result of the request.

Example: OK

Inbound message details

GET
https://api.postmarkapp.com
/messages/inbound/{messageId}/details

Returns the full details of a received message, including bodies, headers and attachment metadata.

Inbound message details › path Parameters

messageId
​string · uuid · required

Unique ID of the message (MessageID returned when sending).

Inbound message details › Responses

The message details.

Full details of an inbound message.
From
​string

Sender email address.

Example: dart-zzzzz@example.com
FromName
​string

Sender name.

Example: Dart Zzzzz
​InboundAddress

An address on an inbound message.

To
​string

To recipients as a string.

Example: ad8a4d0842c486355a33a7f019caab51@inbound.postmarkapp.com
​InboundAddress[]

To recipients.

Example: [{"Email":"dart-zzzzz@example.com","Name":"Dart Zzzzz","MailboxHash":""}]
Cc
​string

Cc recipients as a string.

Example:
​InboundAddress[]

Cc recipients.

Example: [{"Email":"dart-zzzzz@example.com","Name":"Dart Zzzzz","MailboxHash":""}]
ReplyTo
​string

Reply-To address.

Example:
OriginalRecipient
​string

Receiver (RCPT TO) address.

Example: ad8a4d0842c486355a33a7f019caab51@inbound.postmarkapp.com
Subject
​string

Subject.

Example: Test
Date
​string

Date header of the message.

Example: Thu, 13 Feb 2014 17:48:22 +0300
MailboxHash
​string

Custom hash the email was sent to.

Example:
Tag
​string

Tag.

Example:
​InboundAttachment[]

Attachments.

Example: [{"Name":"myimage.png","ContentID":"myimage.png@01CE7342.75E71F80","ContentType":"image/png","ContentLength":4096}]
MessageID
​string · uuid

Unique ID of the message. Field of InboundMessageDetails.

Example: cc5727a0-ea30-4e79-baea-aa43c9628ac4
Status
​string · enum

Message status.

Enum values:
Blocked
Processed
Queued
Failed
Scheduled
Example: Processed
TextBody
​string

Plain-text body.

Example: stuff stuff.
HtmlBody
​string

HTML body.

Example:
​CustomHeader[]

All message headers.

Example: [{"Name":"X-Custom-Header","Value":"custom-value"}]
BlockedReason
​string

Reason the message was blocked, when applicable.

Example: Inbound request blocked by domain rule: badsender@example.com

Retry a failed inbound message for processing

PUT
https://api.postmarkapp.com
/messages/inbound/{messageId}/retry

Reschedules an inbound message whose webhook delivery failed so it is processed again.

Retry a failed inbound message for processing › path Parameters

messageId
​string · uuid · required

Unique ID of the message (MessageID returned when sending).

Retry a failed inbound message for processing › Responses

The message was rescheduled.

Generic response returned by operations that only report a result code and message.
ErrorCode
​integer · required

Postmark API error code. 0 means the request succeeded. See the API error code table in the API description.

Example: 0
Message
​string · required

Human-readable result of the request.

Example: OK

GET
https://api.postmarkapp.com
/messages/outbound

Searches sent messages. A search can return up to 10,000 messages; use fromdate and todate to retrieve larger sets. Messages expire after your retention period (45 days by default, configurable from 7 to 365).

Outbound message search › query Parameters

count
​integer · min: 1 · max: 500 · required

Number of records to return per request. Max 500. count + offset cannot exceed 10,000.

offset
​integer · min: 0 · required

Number of records to skip. count + offset cannot exceed 10,000.

recipient
​string

Filter by the recipient of the email. See searchOutboundMessages.

fromemail
​string

Filter by the sender email address. See searchOutboundMessages.

tag
​string

Filter by tag.

status
​string · enum

Filter by status. sent and processed return the same results.

Enum values:
queued
sent
processed
todate
​string

Return records up to this date/time (inclusive), e.g. 2026-01-31T12:00:00. Postmark uses US Eastern Time.

fromdate
​string

Return records starting from this date/time (inclusive), e.g. 2026-01-01T12:00:00. Postmark uses US Eastern Time.

subject
​string

Filter by email subject. See searchOutboundMessages.

messagestream
​string

Filter by message stream ID. Defaults to the outbound transactional stream when omitted.

metadata_
​string

Filter by a metadata value, e.g. metadata_color=blue. Only one metadata field can be searched at a time.

Outbound message search › Responses

A page of outbound messages.

Paged list of outbound messages.
TotalCount
​integer · required

Number of messages matching the search. A message sent to several recipients counts once here.

Example: 194
​OutboundMessageSummary[] · required

Messages for the requested page. Field of OutboundMessageList.

Example: [{"Tag":"welcome-user","MessageID":"927e56d4-dc66-4070-bbf0-1db76c2ae14b","MessageStream":"outbound","To":[{"Email":"john.doe@example.com","Name":"John Doe"}],"Cc":[{"Email":"john.doe@example.com","Name":"John Doe"}],"Bcc":[{"Email":"john.doe@example.com","Name":"John Doe"}],"Recipients":["john.doe@example.com"],"ReceivedAt":"2026-10-06T07:25:02.8782715-04:00","From":"\"Joe\" <joe@example.com>","Subject":"Welcome aboard","Attachments":["report.pdf"],"Status":"Sent","TrackOpens":true,"TrackLinks":"HtmlAndText","Metadata":{"color":"blue","client-id":"12345"},"Sandboxed":false}]

Message clicks

GET
https://api.postmarkapp.com
/messages/outbound/clicks

Searches click events for sent messages. All filters are optional. Each click is bound to one recipient and one unique link.

Message clicks › query Parameters

count
​integer · min: 1 · max: 500 · required

Number of records to return per request. Max 500. count + offset cannot exceed 10,000.

offset
​integer · min: 0 · required

Number of records to skip. count + offset cannot exceed 10,000.

recipient
​string

Filter by recipient (To, Cc or Bcc).

tag
​string

Filter by tag.

client_name
​string

Filter by client name, e.g. Outlook, Gmail.

client_company
​string

Filter by client company, e.g. Microsoft, Apple, Google.

client_family
​string

Filter by client family, e.g. OS X, Chrome.

os_name
​string

Filter by full OS name and version, e.g. OS X 10.9 Mavericks, Windows 7.

os_family
​string

Filter by OS family without version, e.g. OS X, Windows.

os_company
​string

Filter by the company that produced the OS, e.g. Apple Computer, Inc..

platform
​string

Filter by platform: webmail, desktop or mobile.

country
​string

Filter by country, e.g. Denmark.

region
​string

Filter by full region name, e.g. New York.

city
​string

Filter by full city name, e.g. Minneapolis.

messagestream
​string

Filter by message stream ID. Defaults to the outbound transactional stream when omitted.

Message clicks › Responses

A page of clicks.

Paged list of clicks.
TotalCount
​integer · required

Number of clicks matching the search.

Example: 1
​ClickEvent[] · required

Clicks for the requested page.

Example: [{"RecordType":"Click","Client":{"Name":"Chrome 119.0","Company":"Google Inc.","Family":"Chrome"},"OS":{"Name":"OS X 10.7 Lion","Company":"Apple Computer, Inc.","Family":"OS X"},"Platform":"WebMail","UserAgent":"Mozilla/5.0 (Macintosh; Intel Mac OS X 10_7_5) AppleWebKit/537.36","Geo":{"CountryISOCode":"RS","Country":"Serbia","RegionISOCode":"VO","Region":"Autonomna Pokrajina Vojvodina","City":"Novi Sad","Zip":"21000","Coords":"45.2517,19.8369","IP":"188.2.95.4"},"MessageID":"927e56d4-dc66-4070-bbf0-1db76c2ae14b","MessageStream":"outbound","ReceivedAt":"2026-10-06T05:04:23.8768746-04:00","Tag":"welcome-user","Recipient":"john.doe@example.com","OriginalLink":"https://example.com/features","ClickLocation":"HTML"}]

Clicks for a single message

GET
https://api.postmarkapp.com
/messages/outbound/clicks/{messageId}

Returns the click events recorded for one message.

Clicks for a single message › path Parameters

messageId
​string · uuid · required

Unique ID of the message (MessageID returned when sending).

Clicks for a single message › query Parameters

count
​integer · min: 1 · max: 500 · required

Number of records to return per request. Max 500.

offset
​integer · min: 0 · required

Number of records to skip.

Clicks for a single message › Responses

Clicks for the message.

Paged list of clicks.
TotalCount
​integer · required

Number of clicks matching the search.

Example: 1
​ClickEvent[] · required

Clicks for the requested page.

Example: [{"RecordType":"Click","Client":{"Name":"Chrome 119.0","Company":"Google Inc.","Family":"Chrome"},"OS":{"Name":"OS X 10.7 Lion","Company":"Apple Computer, Inc.","Family":"OS X"},"Platform":"WebMail","UserAgent":"Mozilla/5.0 (Macintosh; Intel Mac OS X 10_7_5) AppleWebKit/537.36","Geo":{"CountryISOCode":"RS","Country":"Serbia","RegionISOCode":"VO","Region":"Autonomna Pokrajina Vojvodina","City":"Novi Sad","Zip":"21000","Coords":"45.2517,19.8369","IP":"188.2.95.4"},"MessageID":"927e56d4-dc66-4070-bbf0-1db76c2ae14b","MessageStream":"outbound","ReceivedAt":"2026-10-06T05:04:23.8768746-04:00","Tag":"welcome-user","Recipient":"john.doe@example.com","OriginalLink":"https://example.com/features","ClickLocation":"HTML"}]

Message opens

GET
https://api.postmarkapp.com
/messages/outbound/opens

Searches open events for sent messages. All filters are optional. Each open is bound to one recipient, so a message sent to two recipients who both open it yields two entries.

Message opens › query Parameters

count
​integer · min: 1 · max: 500 · required

Number of records to return per request. Max 500. count + offset cannot exceed 10,000.

offset
​integer · min: 0 · required

Number of records to skip. count + offset cannot exceed 10,000.

recipient
​string

Filter by recipient (To, Cc or Bcc).

tag
​string

Filter by tag.

client_name
​string

Filter by client name, e.g. Outlook, Gmail.

client_company
​string

Filter by client company, e.g. Microsoft, Apple, Google.

client_family
​string

Filter by client family, e.g. OS X, Chrome.

os_name
​string

Filter by full OS name and version, e.g. OS X 10.9 Mavericks, Windows 7.

os_family
​string

Filter by OS family without version, e.g. OS X, Windows.

os_company
​string

Filter by the company that produced the OS, e.g. Apple Computer, Inc..

platform
​string

Filter by platform: webmail, desktop or mobile.

country
​string

Filter by country, e.g. Denmark.

region
​string

Filter by full region name, e.g. New York.

city
​string

Filter by full city name, e.g. Minneapolis.

messagestream
​string

Filter by message stream ID. Defaults to the outbound transactional stream when omitted.

Message opens › Responses

A page of opens.

Paged list of opens.
TotalCount
​integer · required

Number of opens matching the search.

Example: 1
​OpenEvent[] · required

Opens for the requested page.

Example: [{"RecordType":"Open","Client":{"Name":"Chrome 119.0","Company":"Google Inc.","Family":"Chrome"},"OS":{"Name":"OS X 10.7 Lion","Company":"Apple Computer, Inc.","Family":"OS X"},"Platform":"WebMail","UserAgent":"Mozilla/5.0 (Macintosh; Intel Mac OS X 10_7_5) AppleWebKit/537.36","Geo":{"CountryISOCode":"RS","Country":"Serbia","RegionISOCode":"VO","Region":"Autonomna Pokrajina Vojvodina","City":"Novi Sad","Zip":"21000","Coords":"45.2517,19.8369","IP":"188.2.95.4"},"MessageID":"927e56d4-dc66-4070-bbf0-1db76c2ae14b","MessageStream":"outbound","ReceivedAt":"2026-10-06T05:04:23.8768746-04:00","Tag":"welcome-user","Recipient":"john.doe@example.com"}]

Opens for a single message

GET
https://api.postmarkapp.com
/messages/outbound/opens/{messageId}

Returns the open events recorded for one message. Postmark's API stores only the first open, so TotalCount is at most 1; use the open webhook to receive every open.

Opens for a single message › path Parameters

messageId
​string · uuid · required

Unique ID of the message (MessageID returned when sending).

Opens for a single message › query Parameters

count
​integer · min: 1 · max: 500 · required

Number of records to return per request. Max 500.

offset
​integer · min: 0 · required

Number of records to skip.

Opens for a single message › Responses

Opens for the message.

Paged list of opens.
TotalCount
​integer · required

Number of opens matching the search.

Example: 1
​OpenEvent[] · required

Opens for the requested page.

Example: [{"RecordType":"Open","Client":{"Name":"Chrome 119.0","Company":"Google Inc.","Family":"Chrome"},"OS":{"Name":"OS X 10.7 Lion","Company":"Apple Computer, Inc.","Family":"OS X"},"Platform":"WebMail","UserAgent":"Mozilla/5.0 (Macintosh; Intel Mac OS X 10_7_5) AppleWebKit/537.36","Geo":{"CountryISOCode":"RS","Country":"Serbia","RegionISOCode":"VO","Region":"Autonomna Pokrajina Vojvodina","City":"Novi Sad","Zip":"21000","Coords":"45.2517,19.8369","IP":"188.2.95.4"},"MessageID":"927e56d4-dc66-4070-bbf0-1db76c2ae14b","MessageStream":"outbound","ReceivedAt":"2026-10-06T05:04:23.8768746-04:00","Tag":"welcome-user","Recipient":"john.doe@example.com"}]

Outbound message details

GET
https://api.postmarkapp.com
/messages/outbound/{messageId}/details

Returns the full details of a sent message, including bodies and the events that happened to it (delivery, bounces, opens, clicks, subscription changes).

Outbound message details › path Parameters

messageId
​string · uuid · required

Unique ID of the message (MessageID returned when sending).

Outbound message details › Responses

The message details. See getOutboundMessageDetails.

Full details of an outbound message, including bodies and events.

Tag of the message.

Example: welcome-user
MessageID
​BounceWebhookPayload/properties/MessageID · uuid

Unique ID of the message.

Example: 927e56d4-dc66-4070-bbf0-1db76c2ae14b
MessageStream
​Bounce/properties/MessageStream

Message stream the message was sent through.

Example: outbound
​EmailAddress[]

To recipients. Field of OutboundMessageDetails.

Example: [{"Email":"john.doe@example.com","Name":"John Doe"}]
​EmailAddress[]

Cc recipients. Field of OutboundMessageDetails.

Example: [{"Email":"john.doe@example.com","Name":"John Doe"}]
​EmailAddress[]

Bcc recipients.

Example: [{"Email":"john.doe@example.com","Name":"John Doe"}]
Recipients
​string[]

All recipient email addresses.

Example: ["john.doe@example.com"]
ReceivedAt
​string · date-time

Time Postmark processed the message.

Example: 2026-10-06T07:25:02.8782715-04:00
From
​string

Sender address. Field of OutboundMessageDetails.

Example: "Joe" <joe@example.com>
Subject
​string

Subject. Field of OutboundMessageDetails.

Example: Welcome aboard
Attachments
​string[]

Names of attached files.

Example: ["report.pdf"]
Status
​string · enum

Message status in Postmark Activity.

Enum values:
Queued
Sent
Processed
Example: Sent
TrackOpens
​boolean

Whether open tracking was enabled.

Example: true
TrackLinks
​TrackLinks · enum

Link tracking mode. None disables link tracking, HtmlAndText tracks links in both bodies, HtmlOnly tracks only HTML links, TextOnly tracks only plain-text links.

Enum values:
None
HtmlAndText
HtmlOnly
TextOnly
Example: HtmlAndText
​Metadata

Custom key/value metadata attached to a message. Keys and values are strings. Returned in webhook payloads and message details; you can search by a single metadata field at a time.

Example: {"color":"blue","client-id":"12345"}
Sandboxed
​boolean

Whether the message was sent from a sandbox server.

Example: false
TextBody
​string

Plain-text body. Field of OutboundMessageDetails.

Example: Thank you for your order...
HtmlBody
​string

HTML body. Field of OutboundMessageDetails.

Example: <p>Thank you for your order...</p>
Body
​string

Raw message source. Field of OutboundMessageDetails.

Example: SMTP dump data
​MessageEvent[]

Events for this message in the order they occurred.

Example: [{"Recipient":"john.doe@example.com","Type":"Delivered","ReceivedAt":"2026-10-06T07:26:10.8054242-04:00","Details":{"DeliveryMessage":"smtp;250 2.0.0 OK","DestinationServer":"mx.example.com","DestinationIP":"203.0.113.5"}}]

Outbound message dump

GET
https://api.postmarkapp.com
/messages/outbound/{messageId}/dump

Returns the raw source of a sent message. Body is an empty string when no dump is available.

Outbound message dump › path Parameters

messageId
​string · uuid · required

Unique ID of the message (MessageID returned when sending).

Outbound message dump › Responses

The raw message source.

Raw message source.
Body
​string · required

Raw source of the message. Empty string when no dump is available.

Example: From: "John Doe" <john.doe@example.com> Subject: Parts Order #5454 Thank you for your order