A bounce means the recipient's mail server rejected or could not accept the message. Piisend records this as status bounced on the email and may add the address to your suppression list.
Bounce types
| Type | Meaning | Typical action |
|---|---|---|
| Hard bounce | Permanent failure (unknown user, invalid domain) | Suppress address; do not retry |
| Soft bounce | Temporary failure (mailbox full, greylisting) | May retry later; monitor repeated soft bounces |
Step-by-step: handle bounces in your app
1. Register a webhook
Create an HTTPS endpoint and register it in the dashboard under Webhooks. Subscribe to bounce-related event types.
2. Verify signatures
Validate X-Webhook-Signature (HMAC-SHA256) on each payload. Details in Webhooks.
3. Update your user records
When you receive a bounce event, mark the address undeliverable in your database and stop future campaigns to that address.
4. Inspect in the dashboard
Open Emails / Logs, filter by status bounced, and read provider attempt details on GET /emails/{id}.
Automatic suppressions
Hard bounces and spam complaints typically add entries to the suppression list automatically. Sends to suppressed addresses are rejected before queueing.