Add delivery status webhooks for campaign completion reporting
## Problem
When a campaign is marked as "sent" in the UI, there's currently no real-time visibility into delivery failures that occur hours later. Issue #294 documents a scenario where campaigns show as sent while ~50% of emails fail asynchronously. This creates a data integrity gap: the campaign state doesn't reflect actual delivery outcomes, and users have no programmatic way to track which contacts received emails vs. which bounced/failed.
## Why This Matters
1. **User trust**: Users believe campaigns are delivered when marked "sent," but failures are silently occurring
2. **Missing data**: No audit trail of which sends actually succeeded, blocking troubleshooting and compliance
3. **Integration gaps**: External systems (CRMs, analytics platforms) can't react to delivery failures in real-time
4. **Operational blindness**: Support teams can't proactively alert users to partial campaign failures
## Current State
Plunk tracks campaign delivery through AWS SES, but the webhook/event system doesn't expose:
- Per-email delivery status updates (bounce, complaint, send confirmation)
- Campaign-level aggregated delivery reports
- A way for users to subscribe to delivery events via webhooks
## Proposed Solution
Implement campaign delivery status webhooks that fire when:
1. An email in a campaign bounces or receives a complaint
2. A campaign reaches 100% delivery attempt completion
3. Delivery status changes in bulk (e.g., 10+ bounces from a single campaign)
Webhooks should include:
- Campaign ID and name
- Contact ID and email address
- Delivery status (sent, bounce, complaint, etc.)
- AWS SES response metadata
- Timestamp
Users can subscribe to these webhooks via the UI or API to trigger notifications, update contact states, or log delivery metrics.
## Analogy
SendGrid's [Event Webhook](https://docs.sendgrid.com/for-developers/tracking-events/event) and Resend's [webhook](https://resend.com/docs/api-reference/webhooks) both provide real-time delivery events, allowing users to react instantly to failures instead of discovering them in reports hours later.
## Acceptance Criteria
- [ ] Webhook subscription mechanism exists (via UI and API)
- [ ] Webhooks fire for bounce, complaint, and delivery confirmation events
- [ ] Campaign shows aggregate delivery stats (sent, bounced, failed) that update in real-time
- [ ] Documentation explains webhook payload and setup
- [ ] E2E test verifies webhook delivery for a test campaign
---
*Contributed by [Klement Gunndu](https://github.com/KlementMultiverse)*
关闭于 2026-03-07 1 条评论