Workflow: Real-Time Events

Fresh 🌱

Two ways to get events the instant they happen: webhooks (HTTP push to your URL) or WebSockets (persistent connection). Pick by your infrastructure.

flowchart LR
    E[AgentMail event] --> Q{Have a public HTTPS URL?}
    Q -->|Yes, server with public endpoint| W[Webhooks]
    Q -->|No, or behind NAT / serverless| S[WebSockets]
    W --> V[Verify signature -> handle]
    S --> H[Read events off the connection -> handle]

Choose

	Webhooks	WebSockets
Transport	HTTP POST to your URL	Persistent connection
Needs public URL	Yes (ngrok for local)	No
Best for	Servers, cloud functions with public routes	Local dev, behind NAT, quick prototypes
Setup	SOP: Webhook setup	WebSockets quickstart

Events you can subscribe to

message.received, message.sent, message.delivered, message.bounced, message.rejected, message.complained, domain.verified.

Wire-up

• Webhooks: create a subscription, verify the signature on every payload, return 200 fast. See SOP: Webhook setup and Webhook verification.
• WebSockets: open a connection and consume events. See WebSockets and the WebSockets API.

Related

Events · Webhooks overview · Webhooks API · Inbound emails missing? (KB)