Test
Bounded polling
A Playwright or CI test can wait for one message with a deadline. The test owns the lifecycle and can fail synchronously.
Automation feature
Move from inbox polling to event-driven agent workflows.
Notify a service when mail arrives, stream bounded events to an active client, and keep retries and signature verification outside the model loop.
Direct answer
mails0 supports webhook routes and server-sent events so applications can react to inbound mail and delivery changes without constant polling. Webhook integrations should verify HMAC signatures, handle duplicate delivery idempotently, respond quickly, and fetch full message data only after authenticating and matching the intended mailbox.
Decision map
Choose polling, streaming, or webhooks by ownership
- 01Bounded polling
A Playwright or CI test can wait for one message with a deadline. The test owns the lifecycle and can fail synchronously.
- 02Server-sent events
A connected client can observe mailbox activity without rebuilding a webhook receiver, while still keeping a one-way authenticated stream.
- 03Signed webhooks
A backend receives events even when no agent session is open, then verifies, deduplicates, stores state, and schedules downstream work.
Delivery patterns
Choose polling, streaming, or webhooks by ownership
The right event surface depends on whether the caller is a short-lived test, an interactive agent, or a durable backend service.
Interactive
Server-sent events
A connected client can observe mailbox activity without rebuilding a webhook receiver, while still keeping a one-way authenticated stream.
Production
Signed webhooks
A backend receives events even when no agent session is open, then verifies, deduplicates, stores state, and schedules downstream work.
Consumer contract
A production webhook handler has four jobs
-
01
Verify before parsing
Use the raw request body and configured signing secret to verify the HMAC signature before trusting any event fields.
-
02
Deduplicate the event
Persist an event or message identifier so a retry cannot execute the same external action twice.
-
03
Acknowledge quickly
Return success after durable acceptance, then move slow extraction, model calls, or browser work to a queue.
-
04
Retrieve under mailbox scope
Fetch message content only with the intended mailbox credential and pass the minimum required data downstream.
Agent boundary
Events should wake the workflow, not authorize every action
An inbound email can be attacker-controlled input. Treat sender names, links, attachments, and instructions as untrusted data even when the webhook signature proves that mails0 delivered the event.
The event handler should decide which workflow is eligible, while the agent operates under its own tool and approval policy. A signed webhook proves transport authenticity; it does not prove that the message content is safe or that the requested action is authorized.
- Allowlist workflows or sender domains when the use case permits it.
- Scan or reject unsupported attachments before model access.
- Require human confirmation for payments, credential resets, or durable external changes.
- Record message and event IDs so decisions can be audited without copying full bodies into logs.
Operational fit
Event delivery decision table
| Workflow | Recommended mechanism | Why |
|---|---|---|
| One verification email in a test | Bounded wait or polling | Simple synchronous assertion and a clear timeout. |
| Agent UI showing live inbox state | Server-sent events | Low-overhead one-way updates while the client is connected. |
| Always-on processing service | Signed webhook | Works without an active user session and supports queue handoff. |
| High-cost downstream model call | Webhook plus durable queue | Separates transport retry from expensive processing retry. |
| Irreversible external action | Event plus explicit approval gate | Inbound content cannot authorize the action by itself. |
Evidence
Sources and product scope
Product behavior is verified against the mails0 source and documentation. External comparisons link to official vendor documentation checked on 2026-08-15.
- mails0 source repositoryImplementation, license, and deployment source
- mails0 webhook documentationRoute creation and signature verification
- mails0 events documentationServer-sent events interface
Questions and answers
Questions about Webhooks and events
Does mails0 sign webhook requests?
Yes. Webhook routes support HMAC signature verification. Consumers should verify against the raw request body before parsing or acting on an event.
Why can the same webhook arrive more than once?
Retries are normal when delivery acknowledgement is delayed or fails. Consumers should use an event or message identifier to make processing idempotent.
When should I use server-sent events?
Use SSE for an authenticated client that remains connected and needs one-way mailbox updates. Use webhooks for durable backend processing that must run without an active client.
Is a signed webhook message safe for an agent to follow?
No. The signature proves the event came through the configured transport. Email content remains untrusted input and must pass workflow authorization and content controls.
Start with a bounded inbox
Give the agent an inbox, then prove the workflow.
Start with a receive-only temporary mailbox. Move to a permanent identity or self-hosted deployment only after the workflow reaches a real email value event.