Postmark

Postmark Outbound

Postmark Inbound

Message Retrieval

Stats API

Account API

Triggers API

Bounces Retrieval API

Bounces are exposed over a REST-based API, so that you can build your own user interface and/or automate various tasks. The bounce API is:

  • Associated with a server.
  • Using the server API token as authentication. API URL’s will not contain a server ID or any other mechanism to specify the server. You should provide an X-Postmark-Server-Token HTTP header similar to the mail send API.

Get delivery stats

GET /deliverystats

Returns a summary of inactive emails and bounces by type over the entire history of the server.

Get bounces

GET /bounces?type=HardBounce&inactive=true&emailFilter=John&tag=Invitation&count=25&offset=0

Fetches a portion of bounces according to the specified input criteria. Supported filters: type, inactive, email like, tag. Paging: page_size (count), page_start (offset). Bounces are sorted by BouncedAt in a descending order.

Filtering bounces:

  • type – filter by bounce type. Supported types are:
    Type Code
    HardBounce 1
    Transient 2
    Unsubscribe 16
    Subscribe 32
    AutoResponder 64
    AddressChange 128
    DnsError 256
    SpamNotification 512
    OpenRelayTest 1024
    Unknown 2048
    SoftBounce 4096
    VirusNotification 8192
    ChallengeVerification 16384
    BadEmailAddress 100000
    SpamComplaint 100001
    ManuallyDeactivated 100002
    Unconfirmed 100003
    Blocked 100006
    SMTPApiError 100007
    InboundError 100008
    DMARCPolicy 100009
  • inactive – filter by active/inactive status. Note that we have three options here: true, false, and null (no value). To get all bounces no matter if they are active or inactive, do not pass a value.
  • emailFilter – return only bounces whose recipient address contains the provided string.
  • messageID – return only bounces that match the messageID in the query string. (count and offset not required for this search)
  • count – (Required, except for messageID search) Number of bounces to return (limited to 500). See Paging.
  • offset – (Required, except for messageID search) Set the starting point in a list of bounces to return from. See Paging.

Response format: the response is a JSON object in the form:

{
  TotalCount: 500,
  Bounces: [ { Email: "john@example.com", ... }, ... ]
}

For a list of all Bounce properties see the GetBounces response format.

Get a single bounce

GET /bounces/{bounceID}

Get details about a single bounce. Note that the bounce ID is a numeric value that you typically obtain after a getting a list of bounces.

Response:

{
  "ID": [ID],
  "Type": "HardBounce",
  "MessageID" : "d12c2f1c-60f3-4258-b163-d17052546ae4",
  "TypeCode" : 1,
  "Details": "test bounce",
  "Email": "jim@test.com",
  "BouncedAt": "[YESTERDAY]",
  "DumpAvailable": true,
  "Inactive": true,
  "CanActivate": true,
  "Content" : "Return-Path:....",
  "Subject" : "Hello from our app!"
}

Of the properties above several need a detailed explanation:

  • Type: a list of the legal bounce types has been provided in the “Get bounces” API documentation above.
  • BouncedAt is a date in the ISO 8601 format.
  • DumpAvailable will return true only if we store a raw dump of the bounce source. Postmark currently stores dumps for bounces not older than 30 days.
  • Inactive tells if the bounce email has been deactivated.
  • CanActivate indicates if you can reactivate that bounce.

Get bounce dump

GET /bounces/{bounceID}/dump

Returns the raw source of the bounce we accepted. If Postmark does not have a dump for that bounce, it will return an empty string.

Response:

{
  "Body": "Some SMTP gibberish"
}

Get bounce tags

GET /bounces/tags

Returns a list of tags used for the current server.

Response:

[
  "Signup",
  "Commit Notification"
]

Activate a bounce

PUT /bounces/{bounceID}/activate

Activates a deactivated bounce. Note that you do not need to send anything in the request body.
Response:

{
  "Message":"OK",
  "Bounce":
  {
    "Type":"HardBounce",
    ...
  }
}

The response contains a status message, and returns the Bounce object.

Paging

You should never retrieve all bounces as that could be excessively slow for your application. The best way is to get bounces a page at a time. Suppose you have 300 bounces, and you want to display them in pages of 25 items. To fetch the tenth page, you have to provide a count value of 25 and offset of 250. To know how much your bounces are, you need to request a portion first, usually the first page, and the service will return the count in the TotalCount property in the response.

API error codes

Whenever the Postmark server detects an input error it will return an HTTP 422 status code along with a JSON object containing error details: {ErrorCode: 405, Message: "details"}. The ErrorCode field can be used to programmatically detect the type of error. Here are the supported error codes:

407 – Bounce not found
You requested a bounce by ID, but we could not find an entry in our database.
408 – Bounce query exception
You provided bad arguments as a bounces filter.

Bounce hooks

Bounce hooks are a mechanism to get instant notification from Postmark when an email bounces. Upon receiving a bounced email and parsing it, Postmark can notify you by issuing a HTTP request to your server. Bounce hooks are server-specific and you configure the URL on the Server settings page.

Postmark will serialize the parsed bounce as JSON and send it to your server using a HTTP POST request. Here is a sample bounce:

{
  "ID" : [ID],
  "Type" : "HardBounce",
  "Tag" : "Invitation",
  "MessageID" : "d12c2f1c-60f3-4258-b163-d17052546ae4",
  "TypeCode" : 1,
  "Email" : "jim@test.com",
  "BouncedAt" : "2010-04-01",
  "Details" : "test bounce",
  "DumpAvailable" : true,
  "Inactive" : true,
  "CanActivate" : true,
  "Subject" : "Hello from our app!"
}

Troubleshooting a bounce hook

Note that the server settings UI allows you to test your bounce hook and check if everything runs fine. When you click the “Check” your hook handler will receive a test bounce.

A hook may not run due to many reasons: network issues, server or client code. If you get an error from a hook and are not sure if your handler code is failing, try to substitute the hook URL with one hosted on the excellent Requestbin service. It lets you create a unique URL that saves and displays any data that was posted to it. You can use it to log bounce requests and diagnose data parsing problems.

Spam Compaints

Bounce hooks are sent for spam complaints too. This is a recent change in our policy, previously we did not sent hooks for spam complaints. However, for security purposes, email addresses that are registered as spam on the Postmark system cannot be reactivated programmatically (please contact support to reactivate them).

Security

Many people do not want to have a public URL that anyone on the internet can hit and feed fake data in. To help with that, we support HTTP Basic authentication. You can set up your web server security and provide the credentials in the URL like this:

http://username:password@example.com/bouncehook