Skip to content

Bounces

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

What's the Difference?

  • Bounces: Complete historical log of every bounce event with diagnostic details
  • Suppressions: Current list of blocked addresses (includes bounces, complaints, manual blocks)
  • Unsubscribes: User preference opt-outs

Bounce Types:

  • Hard Bounce: Permanent delivery failure (invalid address, domain doesn't exist)
  • Soft Bounce: Temporary failure (mailbox full, server down)
  • Complaint: Recipient marked email as spam
  • Block: Recipient's server blocked delivery (reputation, content filters)

Use Cases:

  • View why a specific email bounced (SMTP diagnostic codes)
  • Analyze bounce rate trends over time
  • Debug delivery issues with detailed error messages
  • Audit trail for compliance
  • Track bounce patterns for a recipient

SMTP Diagnostic 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

Automatic Actions:

  • Hard bounces are automatically added to suppressions
  • Soft bounces are tracked; repeated soft bounces become suppressions
  • All bounce events are logged for analytics

Unlike suppressions (which show only currently blocked addresses), the bounces endpoint provides complete diagnostic information for every bounce that occurred.

Operations

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
  }
}