Retrieve bounces
If you have questions about the API, please visit our API FAQ page.
A bounce happens when an email cannot be delivered to the recipient.
This endpoint allows you to retrieve bounce events so you can monitor delivery issues and maintain a healthy sender reputation.
Retrieve bounce events
Send a GET request to:
https://webapi.inboxroad.com/api/v1/bouncesAuthentication is required. See Authentication.
By default, only hard bounces are returned.
To also receive:
- soft bounces
- expired bounces
add the include_soft=1 query parameter.
Example request
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
| Parameter | Possible values | Description |
|---|---|---|
| last_id | UUID of the last record | Returns records strictly newer than this record’s timelogged. Useful for incremental polling. |
| order | asc, desc | Sort order. Default is desc (newest first). |
| include_soft | 1 | Includes soft and expired bounces. By default, only hard bounces are returned. |
| page | Integer | 1-based page number. |
| page_size | Integer | Number of items per page. Default is 100, maximum is 1000. |
Example with query parameters
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
Responses use the following pagination 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. |