Event Streaming Subscribe to real-time events via SSE with filtering and replay support.
The event streaming API delivers real-time events to your application over Server-Sent Events (SSE). Use it to react to policy decisions, delivery updates, classification results, and journey progress as they happen.
GET https://api.molted.email/v1/agent/events/stream curl -N "https://api.molted.email/v1/agent/events/stream?tenantId=tenant_abc123" \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Accept: text/event-stream" The connection stays open and delivers events as they occur:
data: {"type":"delivery.sent","requestId":"req_001","contactEmail":"user@example.com","timestamp":"2026-03-01T12:00:01Z"} data: {"type":"policy.blocked","requestId":"req_002","reason":"cooldown","contactEmail":"user2@example.com","timestamp":"2026-03-01T12:00:02Z"} data: {"type":"inbound.classified","messageId":"msg_001","intent":"interested","confidence":0.94,"timestamp":"2026-03-01T12:00:03Z"} Use query parameters to filter the event stream:
Parameter Type Description tenantIdstringRequired. Your tenant identifier. eventTypesstringComma-separated list of event types to filter (e.g., delivery.sent or delivery.bounced,delivery.complained). contactEmailstringFilter to events for a specific contact.
curl -N "https://api.molted.email/v1/agent/events/stream?tenantId=tenant_abc123&eventTypes=delivery.bounced&contactEmail=user@example.com" \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Accept: text/event-stream" curl -N "https://api.molted.email/v1/agent/events/stream?tenantId=tenant_abc123&eventTypes=delivery.bounced,delivery.complained,inbound.classified" \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Accept: text/event-stream" Replay missed events by passing since with the ID of the last event you processed. Up to 1,000 events can be replayed.
curl -N "https://api.molted.email/v1/agent/events/stream?tenantId=tenant_abc123&since=evt_abc123" \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Accept: text/event-stream" Pass the id field from the last event your application successfully processed. The stream replays all events that occurred after that event, then transitions to real-time delivery. This gives you at-least-once delivery: save the last seen event ID and pass it on reconnect.
Events flow in two stages: send.* events fire when a request is received and evaluated by the policy engine, then delivery.* events fire as the email moves through the sending pipeline.
Type Description delivery.queuedEmail accepted and queued for sending. delivery.acceptedEmail accepted by the provider. delivery.sentEmail sent to the provider. delivery.deliveredEmail delivered to the recipient's inbox. delivery.deferredDelivery temporarily deferred by the provider. delivery.bouncedEmail bounced (hard or soft). delivery.complainedRecipient marked the email as spam. delivery.failedDelivery failed permanently.
Type Description inbound.classifiedInbound message classified with an intent. inbound.routedInbound message routed to a handler.
Type Description journey.step_completedA journey step completed for a contact. journey.completedA journey run completed for a contact.
Type Description policy.blockedA send request was blocked by the policy engine.
Type Description send.queuedSend request queued for processing. send.approval_pendingSend requires human approval. send.approval_decidedApproval decision made (approved or rejected).
Type Description followup.scheduledA follow-up email was scheduled. followup.executedA scheduled follow-up was sent.
Type Description coordination.lease_acquiredAn agent acquired a contact lease. coordination.lease_releasedA contact lease was released. coordination.consensus_requestedA consensus vote was created.