Retrieve bounces

If you have questions regarding this API, please visit our API FAQ page.

Bounces occur when an email cannot be delivered to the recipient. This endpoint lets you retrieve and analyze bounce events to maintain a healthy sender reputation.

Retrieving bounces

Make a GET request to https://webapi.inboxroad.com/api/v1/bounces with a valid token (see v1 authentication).

By default only hard bounces are returned. Add include_soft=1 to also receive soft and expired bounces.

curl -X GET 'https://webapi.inboxroad.com/api/v1/bounces' \
  -H 'X-API-Key: <your_token>' \
  -H 'Content-Type: application/json'

Response fields

Each bounce record contains the following fields:

Field name	Description
uuid	Unique identifier of the record.
timelogged	Unix timestamp of when the event was logged.
bounce_type	h for hard, s for soft, e for expired message.
sync_type	Synchronization type of the bounce.
rcpt	Recipient (RCPT TO:) being reported.
orig	Originator (from MAIL FROM:).
dsndiag	DSN diagnostic string for the recipient.
bouncecat	Likely category of the bounce.
header_from	From header of the original email.
extra_fields	Any custom headers configured for your account.

Query parameters

Param name	Possible values	Description
last_id	UUID of the last record	Returns records strictly newer than this record’s timelogged. Use for incremental polling.
order	asc, desc	Sort order. desc (newest first) is the default.
include_soft	1	Include soft and expired bounces. By default only hard bounces are returned.
page	Integer	1-based page number.
page_size	Integer	Items per page. Default 100, maximum 1000.

For example:

curl -X GET 'https://webapi.inboxroad.com/api/v1/bounces?last_id=ce95fca7-b028-4f5c-810c-8bddeda4cac6&order=asc&include_soft=1' \
  -H 'X-API-Key: <your_token>' \
  -H 'Content-Type: application/json'

Pagination

Results are paginated with the standard structure:

Field name	Description
count	Total number of records.
next	URL to the next page, or null.
previous	URL to the previous page, or null.
results	List of bounce records.