Real-time Stream (SSE)

GET /inbox/:address/stream

Opens a Server-Sent Events connection. The server polls D1 every 3 seconds and pushes new emails to the client.

Query parameters

Param	Description
since	Unix ms timestamp — only receive emails after this time
token	Session token (required if inbox is password-protected)

Events

new_email

Fires when a new email arrives.

{
  "type": "new_email",
  "email": { "id": "...", "subject": "Hello", "fromAddress": "a@b.com", ... },
  "timestamp": 1713600000000
}

heartbeat

Sent every ~15 seconds to keep the connection alive.

{ "type": "heartbeat", "timestamp": 1713600000000 }

Example (browser)

const es = new EventSource('https://api.maile.uk/inbox/hello@maile.uk/stream')

es.addEventListener('new_email', (e) => {
  const { email } = JSON.parse(e.data)
  console.log('New email from', email.fromAddress)
})

Example (curl)

curl -N "https://api.maile.uk/inbox/hello@maile.uk/stream"