Pair Webhooks and SSE for Mailbox First Event Streaming for Developers
The best approach pairs signed HMAC webhooks for backend consumers with Server-Sent Events (SSE) for browsers and low-infrastructure clients, wrapped in CloudEvents-style metadata, idempotency identifiers and asynchronous queue processing. This combination gives agent mailboxes and multi-tenant platforms a delivery model that survives retries, duplicate events and out-of-order arrival without losing data or blocking a producer.
TL;DR:
- Implementing signed HMAC webhooks with retries and SSE supports reliable, ordered event delivery regardless of out-of-order or duplicate messages.
- Core email events like received, delivered, bounced, and complaints should be prioritised to trigger relevant agent workflows swiftly.
- Standardising event formats with CloudEvents and assigning stable idempotency identifiers ensures consistent routing, filtering, and deduplication.
- Webhook security relies on verifying signatures with scoped credentials, rotating secrets regularly, and isolating mailbox access per tenant.
- Operational practices should include logging all delivery attempts, monitoring bounce and complaint metrics, and routing failures to dead-letter queues.
Table of Contents
What email event streaming means for agent mailboxes
For agent-scale infrastructure, email event streaming means getting notified the moment something happens to a message: it was received, delivered, bounced, complained about, rejected, delayed, or flagged as spam-received. These are the outcomes that matter when an agent needs to act on mail rather than just read it.
Persistent mailboxes change how we think about these events. A webhook callback used to be the entire interaction: fire, forget, done. With a persistent mailbox behind the event, the webhook becomes a pointer, not the payload. An agent fetches cleaned message text with quoted history stripped, rather than parsing a raw MIME thread from inside a callback handler, which keeps the event itself small and the processing logic separate from ingestion.
Most teams over-subscribe at first and pay for it in noise. Worth pruning to:
- Received and delivered, the core signals for confirming an agent's mail actually moved.
- Bounced and rejected, which usually need code paths, not just logging.
- Complained and spam-received, which affect sending reputation and deserve fast handling.
- Delayed, useful mainly where latency-sensitive workflows need early warning.
Delivery methods: signed webhooks versus Server-Sent Events (SSE)
Webhooks are an HTTP POST model: a producer calls a URL the consumer hosts, expects a fast response, and retries on failure or timeout. That means hosting obligations sit with the consumer, including TLS, uptime and a handler that acknowledges quickly before doing any real work. GitHub's webhook best-practices guidance recommends responding within short windows, typically 10 to 30 seconds, and pushing the actual processing onto a background queue.
SSE flips the model: the client opens a long-lived connection with EventSource and the server pushes events down it. According to MDN's documentation on server-sent events, browsers reconnect automatically and send a Last-Event-ID header so the server can replay anything missed, though non-HTTP/2 browsers cap the number of concurrent connections per origin.
- Prefer webhooks for backend services, queue workers and anything that needs guaranteed delivery with retry semantics.
- Prefer SSE for dashboards, agent consoles and clients that cannot host a public endpoint.
- Supporting both means the producer owns delivery guarantees once, and consumers pick the transport that fits their infrastructure.
Pro Tip: Expose both a webhook and an SSE endpoint on the same event source so a prototype can start on SSE and graduate to webhooks without changing the event schema.
Event format and delivery semantics: CloudEvents, idempotency and retries
Standardising on a CloudEvents-style envelope solves a problem most teams hit only after they have three event types and two consumers: routing and interoperability get messy without a common schema. The CloudEvents primer defines structured, binary and batched content modes for HTTP, letting a producer emit one format that any properly-built consumer can route, filter or forward to a dead-letter queue without the emitter changing a line of code.
A few format decisions carry real operational weight:
- Keep events compact. Link to larger payloads rather than embedding them, since intermediaries and constrained consumers often enforce size ceilings.
- Attach a stable idempotency identifier to every event, scoped consistently across retries.
- Treat every delivery attempt as best-effort. No universal contract guarantees exactly-once delivery.
- Classify outcomes explicitly (delivered, duplicate, terminal failure) so retry logic can branch correctly.
The IETF draft on event and webhook delivery semantics is blunt about this: there is no universally adopted delivery contract for webhooks, so implementations have to design explicitly for duplicates, out-of-order arrival and clear retry signalling, with the idempotency identifier preserved across retries so consumers can deduplicate consistently.
A webhook or SSE event typically needs to stay under roughly 64 kilobytes to clear common intermediary limits, according to the CloudEvents specification, which is why linking to larger data rather than inlining it is the safer default for any high-volume mailbox event stream.
Security and scoped credentials for webhooks and mailbox access
Every webhook endpoint should verify an HMAC-SHA256 signature before trusting a payload, comparing it against a secret stored outside source control and rotated periodically. GitHub's guidance is specific here: a high-entropy secret, a signature header, and rejection of anything that fails verification, because an unverified webhook endpoint is an open door for spoofed events.
Credentials need the same discipline as payloads:
- Scope mailbox keys to one mailbox with explicit permissions, never a blanket key shared across tenants.
- Limit agent tokens to only the scopes a given workflow actually needs, send versus read versus update.
- Add replay protection with unique delivery IDs so a resent webhook cannot be processed twice as if it were new.
- Use IP allowlists where the consumer's infrastructure is static enough to support them.
- Enforce tenant isolation through role-based access so one workspace's credentials cannot touch another's mailbox.
Pro Tip: Store webhook secrets in a secrets manager, not environment files checked into a repository, and rotate them on any team membership change.
Operational concerns: scaling, observability and failure handling
Operational maturity here comes down to four habits: respecting rate limits, logging every attempt, classifying failures correctly, and alerting before a problem becomes a reputation problem.
Sender-side quotas and per-provider throttles stop one noisy tenant from degrading delivery for everyone else sharing the same outbound path. On the receiving side, logging delivery attempts, including attempt count, latency and payload, is what makes a bounce spike diagnosable rather than mysterious three days later.
Failures split into two buckets: transient (timeouts, temporary provider issues) warrant exponential backoff and a retry, while terminal (hard bounces, permanent rejections) belong in a dead-letter queue rather than a retry loop that never succeeds, a split the IETF delivery-semantics draft formalises as transient versus terminal outcomes.
| Signal | Typical threshold | Action |
|---|---|---|
| Bounce rate | Rising above baseline | Investigate list quality, pause affected sends |
| Complaint rate | Rising above baseline | Review content and sending cadence immediately |
| Delivery latency | Increasing attempt count | Check provider health, consider failover |
| Dead-letter volume | Growing queue depth | Audit terminal failure classification |
- Log every attempt with status, latency and recipient, filterable and exportable for debugging.
- Expose bounce and complaint metrics separately from raw delivery counts.
- Push terminal failures to a dead-letter queue instead of retrying indefinitely.
- Monitor provider health continuously and fail over automatically when one account degrades.
How Sendmux implements mailbox-first event streaming for agents
We built our mailbox infrastructure around the same principles outlined above, because an agent mailbox has to behave like persistent state, not a one-shot webhook drop. We offer an SSE stream at GET /api/v1/mailbox/events for clients that cannot host a public endpoint, alongside signed webhooks for backend consumers, each filterable by mailbox and event type and signed with HMAC-SHA256 in the X-Sendmux-Signature header.
Behind both delivery modes sits the same persistent Mailbox API: messages, threads, folders and sync tokens that let an agent poll for state changes instead of re-listing an entire inbox. Agents read cleaned message text with quoted history already stripped, so a reply gets processed without an agent parsing raw MIME, while raw body endpoints remain available when the original is needed.
Credentials follow a scoped model rather than one shared key:
- An infrastructure key (
smx_root_) covers team-wide account and billing operations but is rejected on mailbox endpoints.
- A mailbox key (
smx_mbx_) is scoped to one mailbox with explicit send, receive, read and update permissions.
- An agent token (
smx_agent_) carries only the scopes granted during onboarding, so a newly self-registered agent can receive mail before it is ever trusted to send.
Webhook attempts, status, latency and payloads are retained for 7 days, which gives teams a real debugging window rather than a single delivery attempt they have to catch live. Delivery logs, provider health metrics and CSV exports sit alongside this, so bounce and complaint thresholds can be monitored the same way we described as good practice above, on the mail infrastructure actually carrying the traffic.
Opinion: pick the simplest reliable event architecture
Most teams over-engineer the event schema before they have even picked a delivery mode, and under-engineer idempotency once they have three consumers racing to process the same event. Start simple: one webhook, one idempotency key, a queue in front of processing. The SDKs, CLI and quick-start docs exist precisely so that prototype takes an afternoon, not a sprint.
Try Sendmux for agent mailboxes and event streaming
If your agents or tenants need real inboxes with event streaming built in rather than stitched together from a sending provider, a Gmail OAuth hack and a separate webhook relay, our inbound mailboxes give every agent, workspace or customer a persistent mailbox with webhooks and SSE included on every plan. Pairing that with our email sending API with provider failover means routing, quotas and health checks live in the same place as the inbox itself.
Start on the Free plan to prototype, move to Pro plus usage once you're sending real volume, and check our solutions for AI-agent builders if agent mailboxes are the core of what you're building.
Sources
Frequently Asked Questions
What's the difference between webhooks and SSE for email events?
Webhooks are server-to-server HTTP POST callbacks that your backend hosts and that support retries on failure, while SSE is a one-way browser-native stream your client opens and that reconnects automatically. Webhooks suit backend processing pipelines; SSE suits dashboards and clients without a public endpoint, as described in MDN's SSE documentation.
How do I prevent duplicate email events from being processed twice?
Attach a stable idempotency identifier to every event and check it against previously processed IDs before acting on a new delivery. The IETF delivery-semantics draft recommends preserving this identifier across retries so consumers can deduplicate consistently.
What email events should an AI agent actually subscribe to?
Most agent workflows only need received, delivered, bounced and complained events, with rejected and spam-received added where reputation monitoring matters. Subscribing to fewer event types keeps payload volume and processing load manageable.
Does Sendmux support both webhooks and SSE for mailbox events?
Yes, we offer signed HMAC-SHA256 webhooks and an SSE stream at GET /api/v1/mailbox/events, filterable by mailbox and event type. Both run on the same persistent Mailbox API so agents work from cleaned, threaded message data rather than raw MIME.
How much does Sendmux cost for inbound mailbox events?
Inbound mailbox delivery is billed per distinct mailbox delivery, with the Free plan including two mailboxes and the Pro plan removing plan-level resource limits; current prices are listed on our pricing page.
