Messages
Search and inspect sent and received messages, and query open and click events.
Inbound message search
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.
query Parameters
countNumber of records to return per request. Max 500. count + offset cannot exceed 10,000.
offsetNumber of records to skip. count + offset cannot exceed 10,000.
recipientFilter by the recipient of the email.
fromemailFilter by the sender email address.
tagFilter by tag.
subjectFilter by email subject.
mailboxhashFilter by mailbox hash.
statusFilter by status. Defaults to processed, so only processed messages are returned unless you ask otherwise.
todateReturn records up to this date/time (inclusive), e.g. 2026-01-31T12:00:00. Postmark uses US Eastern Time.
fromdateReturn 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.
TotalCountNumber of messages matching the search.
Messages for the requested page.
Bypass rules for a blocked inbound message
Releases an inbound message that was blocked by an inbound rule so that it is processed normally.
path Parameters
messageIdUnique ID of the message (MessageID returned when sending).
Bypass rules for a blocked inbound message › Responses
The message was released.
ErrorCodePostmark API error code. 0 means the request succeeded. See the API error code table in the API description.
MessageHuman-readable result of the request.
Inbound message details
Returns the full details of a received message, including bodies, headers and attachment metadata.
path Parameters
messageIdUnique ID of the message (MessageID returned when sending).
Inbound message details › Responses
The message details.
FromSender email address.
FromNameSender name.
An address on an inbound message.
ToTo recipients as a string.
To recipients.
CcCc recipients as a string.
Cc recipients.
ReplyToReply-To address.
OriginalRecipientReceiver (RCPT TO) address.
SubjectSubject.
DateDate header of the message.
MailboxHashCustom hash the email was sent to.
TagTag.
Attachments.
MessageIDUnique ID of the message. Field of InboundMessageDetails.
StatusMessage status.
TextBodyPlain-text body.
HtmlBodyHTML body.
All message headers.
BlockedReasonReason the message was blocked, when applicable.
Retry a failed inbound message for processing
Reschedules an inbound message whose webhook delivery failed so it is processed again.
path Parameters
messageIdUnique ID of the message (MessageID returned when sending).
Retry a failed inbound message for processing › Responses
The message was rescheduled.
ErrorCodePostmark API error code. 0 means the request succeeded. See the API error code table in the API description.
MessageHuman-readable result of the request.
Outbound message search
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).
query Parameters
countNumber of records to return per request. Max 500. count + offset cannot exceed 10,000.
offsetNumber of records to skip. count + offset cannot exceed 10,000.
recipientFilter by the recipient of the email. See searchOutboundMessages.
fromemailFilter by the sender email address. See searchOutboundMessages.
tagFilter by tag.
statusFilter by status. sent and processed return the same results.
todateReturn records up to this date/time (inclusive), e.g. 2026-01-31T12:00:00. Postmark uses US Eastern Time.
fromdateReturn records starting from this date/time (inclusive), e.g. 2026-01-01T12:00:00. Postmark uses US Eastern Time.
subjectFilter by email subject. See searchOutboundMessages.
messagestreamFilter by message stream ID. Defaults to the outbound transactional stream when omitted.
metadata_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.
TotalCountNumber of messages matching the search. A message sent to several recipients counts once here.
Messages for the requested page. Field of OutboundMessageList.
Message clicks
Searches click events for sent messages. All filters are optional. Each click is bound to one recipient and one unique link.
query Parameters
countNumber of records to return per request. Max 500. count + offset cannot exceed 10,000.
offsetNumber of records to skip. count + offset cannot exceed 10,000.
recipientFilter by recipient (To, Cc or Bcc).
tagFilter by tag.
client_nameFilter by client name, e.g. Outlook, Gmail.
client_companyFilter by client company, e.g. Microsoft, Apple, Google.
client_familyFilter by client family, e.g. OS X, Chrome.
os_nameFilter by full OS name and version, e.g. OS X 10.9 Mavericks, Windows 7.
os_familyFilter by OS family without version, e.g. OS X, Windows.
os_companyFilter by the company that produced the OS, e.g. Apple Computer, Inc..
platformFilter by platform: webmail, desktop or mobile.
countryFilter by country, e.g. Denmark.
regionFilter by full region name, e.g. New York.
cityFilter by full city name, e.g. Minneapolis.
messagestreamFilter by message stream ID. Defaults to the outbound transactional stream when omitted.
Message clicks › Responses
A page of clicks.
TotalCountNumber of clicks matching the search.
Clicks for the requested page.
Clicks for a single message
Returns the click events recorded for one message.
path Parameters
messageIdUnique ID of the message (MessageID returned when sending).
query Parameters
countNumber of records to return per request. Max 500.
offsetNumber of records to skip.
Clicks for a single message › Responses
Clicks for the message.
TotalCountNumber of clicks matching the search.
Clicks for the requested page.
Message 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.
query Parameters
countNumber of records to return per request. Max 500. count + offset cannot exceed 10,000.
offsetNumber of records to skip. count + offset cannot exceed 10,000.
recipientFilter by recipient (To, Cc or Bcc).
tagFilter by tag.
client_nameFilter by client name, e.g. Outlook, Gmail.
client_companyFilter by client company, e.g. Microsoft, Apple, Google.
client_familyFilter by client family, e.g. OS X, Chrome.
os_nameFilter by full OS name and version, e.g. OS X 10.9 Mavericks, Windows 7.
os_familyFilter by OS family without version, e.g. OS X, Windows.
os_companyFilter by the company that produced the OS, e.g. Apple Computer, Inc..
platformFilter by platform: webmail, desktop or mobile.
countryFilter by country, e.g. Denmark.
regionFilter by full region name, e.g. New York.
cityFilter by full city name, e.g. Minneapolis.
messagestreamFilter by message stream ID. Defaults to the outbound transactional stream when omitted.
Message opens › Responses
A page of opens.
TotalCountNumber of opens matching the search.
Opens for the requested page.
Opens for a single message
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.
path Parameters
messageIdUnique ID of the message (MessageID returned when sending).
query Parameters
countNumber of records to return per request. Max 500.
offsetNumber of records to skip.
Opens for a single message › Responses
Opens for the message.
TotalCountNumber of opens matching the search.
Opens for the requested page.
Outbound message details
Returns the full details of a sent message, including bodies and the events that happened to it (delivery, bounces, opens, clicks, subscription changes).
path Parameters
messageIdUnique ID of the message (MessageID returned when sending).
Outbound message details › Responses
The message details. See getOutboundMessageDetails.
Tag of the message.
MessageIDUnique ID of the message.
MessageStreamMessage stream the message was sent through.
To recipients. Field of OutboundMessageDetails.
Cc recipients. Field of OutboundMessageDetails.
Bcc recipients.
RecipientsAll recipient email addresses.
ReceivedAtTime Postmark processed the message.
FromSender address. Field of OutboundMessageDetails.
SubjectSubject. Field of OutboundMessageDetails.
AttachmentsNames of attached files.
StatusMessage status in Postmark Activity.
TrackOpensWhether open tracking was enabled.
TrackLinksLink tracking mode. None disables link tracking, HtmlAndText tracks links in both bodies, HtmlOnly tracks only HTML links, TextOnly tracks only plain-text links.
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.
SandboxedWhether the message was sent from a sandbox server.
TextBodyPlain-text body. Field of OutboundMessageDetails.
HtmlBodyHTML body. Field of OutboundMessageDetails.
BodyRaw message source. Field of OutboundMessageDetails.
Events for this message in the order they occurred.
Outbound message dump
Returns the raw source of a sent message. Body is an empty string when no dump is available.
path Parameters
messageIdUnique ID of the message (MessageID returned when sending).
Outbound message dump › Responses
The raw message source.
BodyRaw source of the message. Empty string when no dump is available.