Skip to content

Bounce and Complaint Handling

Jump to bottom
Tyler Hatfield edited this page Jul 13, 2026 · 1 revision

Bounce & Complaint Handling

PolyPress processes hard bounces, automated complaints, and spam reports through two primary inbound channels: IMAP polling or incoming HTTP webhooks.

📥 IMAP Mailbox Scanners

If you deliver emails directly or through an SMTP service that routes bounce notifications back to a custom Return-Path mailbox, you can configure PolyPress to poll that mailbox:

  1. Navigate to Sending Settings -> IMAP Bounce Box.
  2. Provide the IMAP host, port, username, password, and security preferences.
  3. The background worker periodically opens a connection, downloads incoming messages, and parses them:
    • Delivery Status Notifications (DSNs): Identifies standard bounce templates (RFC 3464) and flags the recipient as bounced.
    • Feedback Loops (ARF): Parses Abuse Reporting Format (ARF) complaints (RFC 5965) and flags the recipient as complained.
  4. Processed messages can be configured to be automatically deleted from the mailbox to keep it clean.

⚡ Incoming Webhooks (External SMTP Relays)

If you use third-party SMTP relays, you can configure them to route bounce and complaint events directly to PolyPress via HTTP POST webhooks.

Configuration Steps

  1. Go to Sending Settings -> Bounce Webhooks.
  2. Select your SMTP provider (SendGrid, Mailgun, Postmark, or Amazon SES) to generate a copyable webhook URL.
  3. Paste the webhook URL into your provider's event dashboard:
    • SendGrid: Enable Bounced and Spam Reports event webhooks.
    • Mailgun: Set up webhooks for Permanent Failure (bounce) and Spam Complaint events.
    • Postmark: Enable Bounce and Spam Complaint webhooks.
    • Amazon SES: Map bounce and complaint notifications to an SNS HTTP endpoint pointing to PolyPress.
+-------------------+      POST Event Webhook      +--------------------+
| SMTP Provider     | ---------------------------> | PolyPress Instance |
| (SendGrid/Mailgun)|                              |                    |
+-------------------+                              +--------------------+

Security Tokens

Webhook endpoints include a secure token parameter. If you suspect a token has been compromised, you can rotate the secret directly in the UI to secure the endpoint.

Clone this wiki locally