bounce handling email api

If you want bounce handling for an email API, the usual approach is:

What “bounce handling” means

When an email can’t be delivered, the mail provider returns a bounce or delivery failure event. You should capture that event and update your system accordingly.

Common ways to handle it

1. Webhook / event callback

   • Your email provider sends a POST request to your endpoint when a bounce happens.
   • Best option for real-time processing.

2. Bounce mailbox

   • Some providers let you set a special return-path/bounce address and you process incoming mail there.
   • Less common with modern APIs.

3. Event polling

   • Your app periodically checks the provider’s API for bounce events.
   • Simpler sometimes, but not real-time.

What to store

When a bounce comes in, save:

• recipient email
• message ID / campaign ID
• bounce type: hard / soft
• bounce reason / diagnostic code
• timestamp
• provider event ID

How to react

• Hard bounce: permanently mark the address as invalid.
• Soft bounce: retry later; if repeated, suppress temporarily or permanently.
• Update unsubscribe/suppression lists.
• Notify support if needed.

Example webhook flow

1. Send email via API.
2. Provider returns message ID.
3. Provider detects failure.
4. Provider calls your webhook with bounce data.
5. Your backend:
   • verifies signature
   • parses bounce type
   • updates user/email status
   • logs event
   • optionally triggers retry or suppression

Important implementation details

• Verify webhook signatures to prevent spoofing.
• Handle duplicate events safely using idempotency.
• Use a queue if bounce processing is heavy.
• Keep audit logs for compliance.

Example webhook payload

{
  "event": "bounce",
  "message_id": "abc123",
  "recipient": "user@example.com",
  "bounce_type": "hard",
  "reason": "mailbox does not exist",
  "timestamp": "2026-11-06T12:00:00Z"
}

If you want, I can also provide:

• a Node.js / Python / PHP webhook example
• a bounce handling database schema
• or provider-specific setup for SendGrid, SES, Mailgun, Postmark, or Resend.