Overview

Integration

User guide

API reference

Webhooks

Bounce API

Lets you access all reports regarding your bounces for a specific server. Bounces are available for your retention period, which is 45 days by default.

Get delivery stats Try → #

get

/deliverystats

Request headers

Accept required

application/json
X-Postmark-Server-Token required

This request requires server level privileges. This token can be found from the API Tokens tab under your Postmark server.

Example request with curl

curl "https://api.postmarkapp.com/deliverystats" \
  -X GET \
  -H "Accept: application/json" \
  -H "X-Postmark-Server-Token: server token"

Response

InactiveMails integer

Number of inactive emails
Bounces array

List of bounce types with total counts.

Example response

HTTP/1.1 200 OK
Content-Type: application/json

{
  "InactiveMails": 192,
  "Bounces": [
    {
      "Name": "All",
      "Count": 253
    },
    {
      "Type": "HardBounce",
      "Name": "Hard bounce",
      "Count": 195
    },
    {
      "Type": "Transient",
      "Name": "Message delayed",
      "Count": 10
    },
    {
      "Type": "AutoResponder",
      "Name": "Auto responder",
      "Count": 14
    },
    {
      "Type": "SpamNotification",
      "Name": "Spam notification",
      "Count": 3
    },
    {
      "Type": "SoftBounce",
      "Name": "Soft bounce",
      "Count": 30
    },
    {
      "Type": "SpamComplaint",
      "Name": "Spam complaint",
      "Count": 1
    }
  ]
}

Get bounces Try → #

get

/bounces

The bounces search allows you to return up-to 10,000 bounces in a search. For searches where you're looking to retrieve more than 10,000 bounces use parameters like todate and fromdate to filter the messages.

Request headers

Accept required

application/json
X-Postmark-Server-Token required

This request requires server level privileges. This token can be found from the API Tokens tab under your Postmark server.

Example request with curl

curl "https://api.postmarkapp.com/bounces?type=HardBounce&inactive=true&count=50&offset=0" \
  -X GET \
  -H "Accept: application/json" \
  -H "X-Postmark-Server-Token: server token"

Querystring parameters

count required

Number of bounces to return per request. Max 500. Count + Offset cannot exceed 10,000 bounces.
offset required

Number of bounces to skip. Count + Offset cannot exceed 10,000 bounces.
type

Filter by type of bounce
inactive

Filter by emails that were deactivated by Postmark due to the bounce. Set to true or false. If this isn’t specified it will return both active and inactive.
emailFilter

Filter by email address
tag

Filter by tag
messageID

Filter by messageID
fromdate

Filter messages starting from the date/time specified (inclusive) using Eastern Time Zone. e.g. YYYY-MM-DDT12:00:00.
todate

Filter messages up to the date/time specified (inclusive) using Eastern Time Zone. e.g. YYYY-MM-DDT23:00:00.
messagestream

Filter by message stream ID. If not provided, message will default to the outbound transactional stream.

Response

TotalCount integer

Number of records returned
Bounces array

List of individual bounces
RecordType string

Type of record
ID integer

ID of bounce
Type string

Bounce type
TypeCode integer

Bounce type code
Name string

Bounce type name
Tag string

Tag name
MessageID string

ID of message
ServerID string

ID of server that sent the message
MessageStream string

The outbound sending message stream for the message.
Description string

Description of bounce
Details string

Details on the bounce
Email string

Email address that bounced
From string

Original sender of the bounced message, if available. For example, spam complaints do not include the original sender address.
BouncedAt string

Timestamp of bounce
DumpAvailable boolean

Specifies whether or not you can get a raw dump from this bounce. Postmark doesn’t store bounce dumps older than 30 days.
Inactive boolean

Specifies if the bounce caused Postmark to deactivate this email.
CanActivate boolean

Specifies whether or not you are able to reactivate this email.
Subject string

Email subject
Content string

Bounce content

Example response

HTTP/1.1 200 OK
Content-Type: application/json

{
  "TotalCount": 253,
  "Bounces": [
    {
      "RecordType": "Bounce",
      "ID": 692560173,
      "Type": "HardBounce",
      "TypeCode": 1,
      "Name": "Hard bounce",
      "Tag": "Invitation",
      "MessageID": "2c1b63fe-43f2-4db5-91b0-8bdfa44a9316",
      "ServerID": 23,
      "MessageStream": "outbound",
      "Description": "The server was unable to deliver your message (ex: unknown user, mailbox not found).",
      "Details": "action: failed\r\n",
      "Email": "anything@blackhole.postmarkapp.com",
      "From": "sender@postmarkapp.com",
      "BouncedAt": "2014-01-15T16:09:19Z",
      "DumpAvailable": false,
      "Inactive": true,
      "CanActivate": true,
      "Subject": "SC API5 Test"
    },
    {
      "RecordType": "Bounce",
      "ID": 676862817,
      "Type": "HardBounce",
      "TypeCode": 1,
      "Name": "Hard bounce",
      "Tag": "Invitation",
      "MessageID": "623b2e90-82d0-4050-ae9e-2c3a734ba091",
      "ServerID": 23,
      "MessageStream": "outbound",
      "Description": "The server was unable to deliver your message (ex: unknown user, mailbox not found).",
      "Details": "smtp;554 delivery error: dd This user doesn't have a yahoo.com account (vicelcown@yahoo.com) [0] - mta1543.mail.ne1.yahoo.com",
      "Email": "vicelcown@yahoo.com",
      "From": "sender@postmarkapp.com",
      "BouncedAt": "2013-10-18T09:49:59Z",
      "DumpAvailable": false,
      "Inactive": true,
      "CanActivate": true,
      "Subject": "Production API Test"
    }
  ]
}

Get a single bounce Try → #

get

/bounces/{bounceid}

Request headers

Accept required

application/json
X-Postmark-Server-Token required

This request requires server level privileges. This token can be found from the API Tokens tab under your Postmark server.

Example request with curl

curl "https://api.postmarkapp.com/bounces/{bounceid}" \
  -X GET \
  -H "Accept: application/json" \
  -H "X-Postmark-Server-Token: server token"

Response

ID integer

ID of bounce
Type string

Bounce type
TypeCode integer

Bounce type code
Name string

Bounce type name
Tag string

Tag name
MessageID string

ID of message
ServerID string

ID of server that sent the message
MessageStream string

The outbound sending message stream for the message.
Description string

Description of bounce
Details string

Details on the bounce
Email string

Email address that bounced
From string

Original sender of the bounced message, if available. For example, spam complaints do not include the original sender address.
BouncedAt string

Timestamp of bounce
DumpAvailable boolean

Specifies whether or not you can get a raw dump from this bounce. Postmark doesn’t store bounce dumps older than 30 days.
Inactive boolean

Specifies if the bounce caused Postmark to deactivate this email.
CanActivate boolean

Specifies whether or not you are able to reactivate this email.
Subject string

Email subject
Content string

Bounce content

Example response

HTTP/1.1 200 OK
Content-Type: application/json

{
  "ID": 692560173,
  "Type": "HardBounce",
  "TypeCode": 1,
  "Name": "Hard bounce",
  "Tag": "Invitation",
  "MessageID": "2c1b63fe-43f2-4db5-91b0-8bdfa44a9316",
  "ServerID": 23,
  "MessageStream": "outbound",
  "Description": "The server was unable to deliver your message (ex: unknown user, mailbox not found).",
  "Details": "action: failed\r\n",
  "Email": "anything@blackhole.postmarkapp.com",
  "From": "sender@postmarkapp.com",
  "BouncedAt": "2014-01-15T16:09:19.6421112-05:00",
  "DumpAvailable": false,
  "Inactive": false,
  "CanActivate": true,
  "Subject": "SC API5 Test",
  "Content": "Return-Path: <>\r\nReceived: …"
}

Get bounce dump Try → #

get

/bounces/{bounceid}/dump

Request headers

Accept required

application/json
X-Postmark-Server-Token required

This request requires server level privileges. This token can be found from the API Tokens tab under your Postmark server.

Example request with curl

curl "https://api.postmarkapp.com/bounces/{bounceid}/dump" \
  -X GET \
  -H "Accept: application/json" \
  -H "X-Postmark-Server-Token: server token"

Response

Body string

Raw source of bounce. If no dump is available this will return an empty string.

Example response

HTTP/1.1 200 OK
Content-Type: application/json

{
  "Body": "SMTP dump data"
}

Activate a bounce Try → #

put

/bounces/{bounceid}/activate

Request headers

Content-Type required

application/json
Accept required

application/json
X-Postmark-Server-Token required

This request requires server level privileges. This token can be found from the API Tokens tab under your Postmark server.

Example request with curl

curl "https://api.postmarkapp.com/bounces/{bounceid}/activate" \
  -X PUT \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -H "X-Postmark-Server-Token: server token" \
  -d ""

Response

Message string

Response message
Bounce object

Bounce details
ID integer

ID of bounce
Type string

Bounce type
TypeCode integer

Bounce type code
Name string

Bounce type name
Tag string

Tag name
MessageID string

ID of message
ServerID string

ID of server that sent the message
MessageStream string

The outbound sending message stream for the message.
Description string

Description of bounce
Details string

Details on the bounce
Email string

Email address that bounced
From string

Original sender of the bounced message, if available. For example, spam complaints do not include the original sender address.
BouncedAt string

Timestamp of bounce
DumpAvailable boolean

Specifies whether or not you can get a raw dump from this bounce. Postmark doesn’t store bounce dumps older than 30 days.
Inactive boolean

Specifies if the bounce caused Postmark to deactivate this email.
CanActivate boolean

Specifies whether or not you are able to reactivate this email.
Subject string

Email subject
Content string

Bounce content

Example response

HTTP/1.1 200 OK
Content-Type: application/json

{
  "Message": "OK",
  "Bounce": {
    "ID": 692560173,
    "Type": "HardBounce",
    "TypeCode": 1,
    "Name": "Hard bounce",
    "Tag": "Invitation",
    "MessageID": "2c1b63fe-43f2-4db5-91b0-8bdfa44a9316",
    "ServerID": 23,
    "MessageStream": "outbound",
    "Description": "The server was unable to deliver your message (ex: unknown user, mailbox not found).",
    "Details": "action: failed\r\n",
    "Email": "anything@blackhole.postmarkapp.com",
    "From": "sender@postmarkapp.com",
    "BouncedAt": "2014-01-15T16:09:19.6421112-05:00",
    "DumpAvailable": false,
    "Inactive": false,
    "CanActivate": true,
    "Subject": "SC API5 Test",
    "Content": "Return-Path: <>\r\nReceived: …"
  }
}

Bounce types #

 

TypeCodeName & Description
HardBounce1Hard bounce — The server was unable to deliver your message (ex: unknown user, mailbox not found).
Transient2Message delayed/Undeliverable — The server could not temporarily deliver your message (ex: Message is delayed due to network troubles).
Unsubscribe16Unsubscribe request — Unsubscribe or Remove request.
Subscribe32Subscribe request — Subscribe request from someone wanting to get added to the mailing list.
AutoResponder64Auto responder — "Autoresponder" is an automatic email responder including nondescript NDRs and some "out of office" replies.
AddressChange128Address change — The recipient has requested an address change.
DnsError256DNS error — A temporary DNS error.
SpamNotification512Spam notification — The message was delivered, but was either blocked by the user, or classified as spam, bulk mail, or had rejected content.
OpenRelayTest1024Open relay test — The NDR is actually a test email message to see if the mail server is an open relay.
Unknown2048Unknown — Unable to classify the NDR.
SoftBounce4096Soft bounce — Unable to temporarily deliver message (i.e. mailbox full, account disabled, exceeds quota, out of disk space).
VirusNotification8192Virus notification — The bounce is actually a virus notification warning about a virus/code infected message.
ChallengeVerification16384Spam challenge verification — The bounce is a challenge asking for verification you actually sent the email. Typcial challenges are made by Spam Arrest, or MailFrontier Matador.
BadEmailAddress100000Invalid email address — The address is not a valid email address.
SpamComplaint100001Spam complaint — The subscriber explicitly marked this message as spam.
ManuallyDeactivated100002Manually deactivated — The email was manually deactivated.
Unconfirmed100003Registration not confirmed — The subscriber has not clicked on the confirmation link upon registration or import.
Blocked100006ISP block — Blocked from this ISP due to content or blacklisting.
SMTPApiError100007SMTP API error — An error occurred while accepting an email through the SMTP API.
InboundError100008Processing failed — Unable to deliver inbound message to destination inbound hook.
DMARCPolicy100009DMARC Policy — Email rejected due DMARC Policy.
TemplateRenderingFailed100010Template rendering failed — An error occurred while attempting to render your template.

Rebound JavaScript Snippet #

The Rebound JavaScript snippet (once installed on your website) will tap into the Postmark API to check for hard bounces and prompt your customers to update their email address if they've experienced deliverability issues in the past.