Overview

Integration

User guide

API reference

Webhooks

Bounce API

Lets you access all reports regarding your bounces for a specific server.

Get delivery stats Try →

Request headers

Accept required
application/json
X-Postmark-Server-Token required
This request requires server level privileges. This token can be found on the Credentials tab under your Postmark server.
get

/deliverystats

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 →

Request headers

Accept required
application/json
X-Postmark-Server-Token required
This request requires server level privileges. This token can be found on the Credentials tab under your Postmark server.

Querystring parameters

count Required
Number of bounces to return per request. Max 500.
offset Required
Number of bounces to skip
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 specified (inclusive). e.g. 2014-02-01
todate Filter messages up to the date specified (inclusive). e.g. 2014-02-01
get

/bounces

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"
            

Response

TotalCount integer Number of records returned
Bounces array List of individual bounces
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
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

Example response

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

{
  "TotalCount": 253,
  "Bounces": [
    {
      "ID": 692560173,
      "Type": "HardBounce",
      "TypeCode": 1,
      "Name": "Hard bounce",
      "Tag": "Invitation",
      "MessageID": "2c1b63fe-43f2-4db5-91b0-8bdfa44a9316",
      "ServerID": 23,
      "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",
    },
    {
      "ID": 676862817,
      "Type": "HardBounce",
      "TypeCode": 1,
      "Name": "Hard bounce",
      "Tag": "Invitation",
      "MessageID": "623b2e90-82d0-4050-ae9e-2c3a734ba091",
      "ServerID": 23,
      "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 →

Request headers

Accept required
application/json
X-Postmark-Server-Token required
This request requires server level privileges. This token can be found on the Credentials tab under your Postmark server.
get

/bounces/{bounceid}

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
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,
  "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 →

Request headers

Accept required
application/json
X-Postmark-Server-Token required
This request requires server level privileges. This token can be found on the Credentials tab under your Postmark server.
get

/bounces/{bounceid}/dump

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 →

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 on the Credentials tab under your Postmark server.
put

/bounces/{bounceid}/activate

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
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,
    "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 bounced tags Try →

Get an array of tags that have generated bounces for a given server.

Request headers

Accept required
application/json
X-Postmark-Server-Token required
This request requires server level privileges. This token can be found on the Credentials tab under your Postmark server.
get

/bounces/tags

Example request with curl

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

Response

[] array List of tags that have generated bounced emails.

Example response

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

[
  "tag1",
  "tag2",
  "tag3"
]

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 — 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 — Automatic email responder (ex: "Out of Office" or "On Vacation").
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 4096 Soft bounce — 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.