Postmark
Postmark API

Search bounces, inspect their raw source and reactivate addresses that Postmark deactivated.


Get bounces

GET
https://api.postmarkapp.com
/bounces

Searches bounces on the server. A search can return up to 10,000 bounces; use fromdate and todate to narrow larger sets.

Get bounces › query Parameters

count
​integer · min: 1 · max: 500 · required

Number of records to return per request. Max 500. count + offset cannot exceed 10,000.

offset
​integer · min: 0 · required

Number of records to skip. count + offset cannot exceed 10,000.

type
​BounceType · enum

Filter by bounce type.

Type of bounce. See the Bounce types section of the Postmark docs for what each value means.

Enum values:
HardBounce
Transient
Unsubscribe
Subscribe
AutoResponder
AddressChange
DnsError
SpamNotification
Example: HardBounce
inactive
​boolean

Filter by whether Postmark deactivated the address because of the bounce. When omitted, both active and inactive bounces are returned.

emailFilter
​string

Filter by email address.

tag
​string

Filter by tag.

messageID
​string · uuid

Filter by the ID of the bounced message.

fromdate
​string

Return records starting from this date/time (inclusive), e.g. 2026-01-01T12:00:00. Postmark uses US Eastern Time.

todate
​string

Return records up to this date/time (inclusive), e.g. 2026-01-31T12:00:00. Postmark uses US Eastern Time.

messagestream
​string

Filter by message stream ID. Defaults to the outbound transactional stream when omitted.

Get bounces › Responses

A page of bounces.

Paged list of bounces.
TotalCount
​integer · required

Number of bounces matching the search. May exceed the number returned in one call.

Example: 253
​Bounce[] · required

Bounces for the requested page.

Example: [{"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":"Test bounce details","Email":"isaac@example.com","From":"sender@example.com","BouncedAt":"2026-10-06T08:11:02.0000000-04:00","DumpAvailable":true,"Inactive":true,"CanActivate":true,"Subject":"Hello from our app","Content":"Return-Path: <>\n..."}]

Get a single bounce

GET
https://api.postmarkapp.com
/bounces/{bounceId}

Returns the details of one bounce, including the raw bounce Content.

Get a single bounce › path Parameters

bounceId
​integer · int64 · required

Unique ID of the bounce.

Get a single bounce › Responses

The bounce.

A bounce record.
ID
​integer · int64

Unique ID of the bounce. Field of Bounce.

Example: 692560173
Type
​BounceType · enum

Type of bounce. See the Bounce types section of the Postmark docs for what each value means.

Enum values:
HardBounce
Transient
Unsubscribe
Subscribe
AutoResponder
AddressChange
DnsError
SpamNotification
Example: HardBounce
TypeCode
​integer

Numeric code of the bounce type.

Example: 1
Name
​string

Display name of the bounce type.

Example: Hard bounce
Tag
​string

Tag of the bounced message.

Example: Invitation
MessageID
​string · uuid

ID of the message that bounced.

Example: 2c1b63fe-43f2-4db5-91b0-8bdfa44a9316
ServerID
​integer

ID of the server that sent the message.

Example: 23
MessageStream
​string

Message stream the message was sent through.

Example: outbound
Description
​string

Short description of the bounce reason.

Example: The server was unable to deliver your message (ex: unknown user, mailbox not found).
Details
​string

Detailed reason reported by the receiving server.

Example: Test bounce details
Email
​string

Email address that bounced.

Example: isaac@example.com
From
​string

Sender address of the bounced message.

Example: sender@example.com
BouncedAt
​string · date-time

Time the bounce occurred.

Example: 2026-10-06T08:11:02.0000000-04:00
DumpAvailable
​boolean

Whether the raw SMTP dump is available (see Get bounce dump).

Example: true
Inactive
​boolean

Whether Postmark deactivated the address because of this bounce.

Example: true
CanActivate
​boolean

Whether the address can be reactivated.

Example: true
Subject
​string

Subject of the bounced message.

Example: Hello from our app
Content
​string

Raw content of the bounce. Only returned when fetching a single bounce.

Example: Return-Path: <> ...

Activate a bounce

PUT
https://api.postmarkapp.com
/bounces/{bounceId}/activate

Reactivates an address that Postmark deactivated because of a bounce, so it can receive email again. Not possible for every bounce type; check CanActivate first (otherwise error code 1003).

Activate a bounce › path Parameters

bounceId
​integer · int64 · required

Unique ID of the bounce.

Activate a bounce › Responses

The reactivated bounce.

Result of reactivating a bounced address.
Message
​string · required

Result of the reactivation attempt.

Example: OK
​Bounce · required

A bounce record.


Get bounce dump

GET
https://api.postmarkapp.com
/bounces/{bounceId}/dump

Returns the raw SMTP source of a bounce. Only available while DumpAvailable is true on the bounce.

Get bounce dump › path Parameters

bounceId
​integer · int64 · required

Unique ID of the bounce.

Get bounce dump › Responses

The raw bounce source.

Raw bounce source.
Body
​string · required

Raw SMTP source of the bounce. Empty string when no dump is available.

Example: Return-Path: <> Received: ...

Get delivery stats

GET
https://api.postmarkapp.com
/deliverystats

Returns a summary of inactive emails and bounces by type for the server.

Get delivery stats › Responses

Bounce summary for the server.

Summary of bounces on a server.
InactiveMails
​integer · required

Number of addresses currently deactivated because of bounces.

Example: 192
​object[] · required

Bounce counts grouped by type. The entry named All is the total.

Example: [{"Type":"HardBounce","Name":"All","Count":253}]