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. eventTypestringFilter to a specific event type (e.g., delivery.sent). contactEmailstringFilter to events for a specific contact.
curl -N "https://api.molted.email/v1/agent/events/stream?tenantId=tenant_abc123&eventType=delivery.bounced&contactEmail=user@example.com" \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Accept: text/event-stream" Replay recent events by passing a since timestamp. Up to 1,000 events can be replayed.
curl -N "https://api.molted.email/v1/agent/events/stream?tenantId=tenant_abc123&since=2026-03-01T11:00:00Z" \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Accept: text/event-stream" After replaying historical events, the stream transitions to real-time delivery.
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.