Skip to content

List bounce events

Request

Get detailed bounce event history with SMTP diagnostic codes and error messages.

Bounces vs Suppressions:

  • Bounces endpoint: Shows complete history of ALL bounce events with diagnostic details
  • Suppressions endpoint: Shows currently blocked addresses (no diagnostic codes)

Use this to:

  • View exact SMTP error codes (550 5.1.1, 452 4.2.2, etc.)
  • Analyze bounce rate trends over time
  • Debug delivery issues with detailed error messages
  • Track bounce patterns for specific recipients
  • Generate bounce analytics and reports

Bounce Types:

  • hard: Permanent delivery failure (invalid address, domain doesn't exist)
  • soft: Temporary failure (mailbox full, server down)
  • complaint: Recipient marked email as spam
  • block: Recipient's server blocked delivery

Common SMTP Status Codes:

  • 550 5.1.1 - User unknown / Mailbox doesn't exist
  • 552 5.2.2 - Mailbox full
  • 553 5.3.0 - Domain doesn't exist
  • 554 5.7.1 - Blocked by recipient server
  • 452 4.2.2 - Mailbox full (temporary)

All hard bounces are automatically added to your suppressions list.

Security
ApiKeyAuth
Query
fromstring, (date-time)

Filter bounces from this date (ISO 8601 format)

Example:from=2026-01-01T00:00:00Z
tostring, (date-time)

Filter bounces to this date (ISO 8601 format)

Example:to=2026-02-26T23:59:59Z
typestring

Filter by bounce type

Enum:"hard""soft""complaint""block""unknown"
recipientstring, (email)

Filter by recipient email address

Example:recipient=user@example.com
limitinteger, [ 1 .. 1000 ]

Number of results to return

Default:100
offsetinteger, >= 0

Pagination offset

Default:0
curl -i -X GET \
  'https://api.mailerlogic.net/api/customer/bounces?from=2026-01-01T00%3A00%3A00Z&to=2026-02-26T23%3A59%3A59Z&type=hard&recipient=user%40example.com&limit=100&offset=0' \
  -H 'X-API-Key: YOUR_API_KEY_HERE'

Responses

Bounce events retrieved successfully

Bodyapplication/json
successboolean
Example:true
dataArray of objects
paginationobject
Response
{
  "success": true,
  "data": [
    { … },
    { … }
  ],
  "pagination": {
    "total": 4,
    "limit": 100,
    "offset": 0
  }
}