Why SSE?

Unlike webhooks, SSE doesn't require your agent to have a public URL. Your agent connects to the stream and receives events as they happen. Perfect for local development, CI/CD, and agents running behind firewalls.

Connection

curl -N -H "Authorization: Bearer YOUR_API_KEY" \
  "https://mails-worker.genedai.workers.dev/v1/events"

Query Parameters

Parameter	Type	Description
mailbox	string	Filter events by mailbox (optional if auth is mailbox-scoped)
types	string	Comma-separated event types (e.g. message.received,message.delivered)
since	string	ISO 8601 timestamp to replay missed events

Event Types

Event	Description
message.received	New inbound email
message.sent	Outbound email accepted
message.delivered	Confirmed delivery to recipient
message.bounced	Permanent delivery failure
message.complained	Marked as spam by recipient

Event Format

event: message.received
data: {
  "event": "message.received",
  "email_id": "abc-123",
  "mailbox": "[email protected]",
  "from": "[email protected]",
  "subject": "Your code is 847293",
  "received_at": "2026-04-03T10:00:00Z",
  "thread_id": "def-456",
  "labels": ["code"],
  "has_attachments": false
}

Connection Behavior

Events use a bounded poll (25 seconds max), not a persistent connection. The server holds the connection open for up to 25 seconds waiting for events, then closes it. Your client should reconnect when the connection closes.

The server sends : keepalive comments every 2 seconds when no events are pending. This keeps the connection alive through proxies and load balancers.

: keepalive
: keepalive
event: message.received
data: {"event":"message.received","email_id":"abc-123",...}
: keepalive

Reconnection

The server supports the Last-Event-ID header for reconnection. When reconnecting, send this header with the last event ID you received to avoid missing events:

curl -N -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Last-Event-ID: evt_abc123" \
  "https://mails-worker.genedai.workers.dev/v1/events"

Python Example

import json
import httpx

with httpx.stream("GET", "https://mails-worker.genedai.workers.dev/v1/events",
                   headers={"Authorization": "Bearer YOUR_KEY"}) as r:
    for line in r.iter_lines():
        if line.startswith("data: "):
            event = json.loads(line[6:])
            print(f"New email from {event['from']}: {event['subject']}")

Node.js Example

const EventSource = require("eventsource")

const es = new EventSource(
  "https://mails-worker.genedai.workers.dev/v1/events",
  { headers: { Authorization: "Bearer YOUR_KEY" } }
)

es.addEventListener("message.received", (e) => {
  const data = JSON.parse(e.data)
  console.log(`New email: ${data.subject}`)
})