AddThisFeature

Notification Delivery Failures

Know when a message failed to arrive and stop sending to addresses that cannot receive it.

involved Admin & Operations

What it adds

Bounce and complaint handling with a suppression list, plus telling the affected user their address is failing.

What your agent is told to do

5
  1. 1

    Consume the delivery provider's webhooks for bounces, complaints, and deferrals, verify their signatures, and deduplicate repeated events by provider event ID.

  2. 2

    Separate hard bounces and spam complaints, which suppress the address permanently, from transient failures, which retry with backoff and only suppress after a threshold.

  3. 3

    Keep the suppression list per channel and per address, and check it before every send. Extend the existing notification preference model with delivery health rather than building a second gate beside it.

  4. 4

    Tell the user in the app when their address is suppressed, and give them a way to correct or reverify it. An invisible suppression looks exactly like a broken product.

  5. 5

    Do NOT let a suppressed email address block push, in-app, or SMS delivery to the same user. Suppression is per channel, never per person.

Edge cases it handles

6
  • A spam complaint must suppress marketing and product mail without stopping password resets, and the boundary needs deciding before launch.
  • Provider webhooks arrive out of order. A delivery event landing after a bounce for the same message must not clear the suppression.
  • A user correcting their address must clear the suppression for the new address only, and require reverification before mail resumes.
  • Admin views must show status and reason without dumping raw provider payloads, which contain recipient data and provider secrets.
  • A provider-wide outage will look like thousands of individual failures — detect the pattern and avoid mass-suppressing valid addresses.
  • Dead push subscriptions belong on the same failure pipeline as bounced email, not in a separate ad hoc cleanup.

Definition of done

8
  • Provider webhooks are signature-verified and deduplicated by event ID.
  • Hard bounces and complaints suppress permanently; transient failures retry with backoff.
  • The suppression list is checked before every send and is scoped per channel.
  • Suppression on one channel does not affect the others.
  • Affected users are told in-app and can correct and reverify their address.
  • Admin views show delivery status and reason without exposing raw provider payloads.
  • The feature matches the existing design system.
  • No existing functionality is broken.

Related features

How it works

  1. 1

    Copy the link

    Grab the Markdown instruction URL for this feature.

  2. 2

    Give it to your AI

    Paste it into Claude Code, Cursor, v0, Lovable — whatever you build with.

  3. 3

    It inspects, then implements

    Your agent reads your existing app first, then adds the feature to fit it.

Works with your stack

These instructions are written to adapt. They tell the agent to detect your framework, match your existing design system, and reuse what you already have — rather than assuming a particular stack.

Need it tighter than that? Customize the feature and tell it exactly what you're running.