Postmark

Postmark Outbound

Postmark Inbound

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.

Get bounces

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

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:
    • HardBounce
    • Transient
    • Unsubscribe
    • Subscribe
    • AutoResponder
    • AddressChange
    • DnsError
    • SpamNotification
    • OpenRelayTest
    • Unknown
    • SoftBounce
    • VirusNotification
    • ChallengeVerification
    • BadEmailAddress
    • SpamComplaint
    • ManuallyDeactivated
    • Unconfirmed
    • Blocked
  • 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.
  • paging: the count and offset parameters are mandatory. 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.

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:

{
  "Type": "HardBounce",
  "Details": "test bounce",
  "Email": "jim@test.com",
  "BouncedAt": "[YESTERDAY]",
  "DumpAvailable": true,
  "Inactive": true,
  "CanActivate": true,
  "ID": [ID]
}

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.

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" : 42,
  "Type" : "HardBounce",
  "Email" : "jim@test.com",
  "BouncedAt" : "2010-04-01",
  "Details" : "test bounce",
  "DumpAvailable" : true,
  "Inactive" : true,
  "CanActivate" : true
}

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 or this PostBin clone . PostBin 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.

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