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). e.g. 2021-01-01T12:00:00. Our API uses Eastern Time Zone.

todate

Filter messages up to the date/time specified (inclusive). e.g. 2021-01-01T12:00:00. Our API uses Eastern Time Zone.

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:19.6421112-05:00",
      "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:59.8253577-04:00",
      "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 #

Type Code Name & Description
HardBounce 1 Hard bounce — The server was unable to deliver your message (ex: unknown user, mailbox not found).
Transient 2 Message delayed/Undeliverable — The server could not temporarily deliver your message (ex: Message is delayed due to network troubles).
Unsubscribe 16 Unsubscribe request — Unsubscribe or Remove request.
Subscribe 32 Subscribe request — Subscribe request from someone wanting to get added to the mailing list.
AutoResponder 64 Auto responder — "Autoresponder" is an automatic email responder including nondescript NDRs and some "out of office" replies.
AddressChange 128 Address change — The recipient has requested an address change.
DnsError 256 DNS error — A temporary DNS error.
SpamNotification 512 Spam notification — The message was delivered, but was either blocked by the user, or classified as spam, bulk mail, or had rejected content.
OpenRelayTest 1024 Open relay test — The NDR is actually a test email message to see if the mail server is an open relay.
Unknown 2048 Unknown — Unable to classify the NDR.
SoftBounce/Undeliverable 4096 Soft bounce/Undeliverable — Unable to temporarily deliver message (i.e. mailbox full, account disabled, exceeds quota, out of disk space).
VirusNotification 8192 Virus notification — The bounce is actually a virus notification warning about a virus/code infected message.
ChallengeVerification 16384 Spam 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.
BadEmailAddress 100000 Invalid email address — The address is not a valid email address.
SpamComplaint 100001 Spam complaint — The subscriber explicitly marked this message as spam.
ManuallyDeactivated 100002 Manually deactivated — The email was manually deactivated.
Unconfirmed 100003 Registration not confirmed — The subscriber has not clicked on the confirmation link upon registration or import.
Blocked 100006 ISP block — Blocked from this ISP due to content or blacklisting.
SMTPApiError 100007 SMTP API error — An error occurred while accepting an email through the SMTP API.
InboundError 100008 Processing failed — Unable to deliver inbound message to destination inbound hook.
DMARCPolicy 100009 DMARC Policy — Email rejected due DMARC Policy.
TemplateRenderingFailed 100010 Template 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.