---
search:
  tags:
    - Inboxes
    - GET
seo:
  description: >-
    BillionSend extension: a server-sent event stream of every inbox event of
    the team,… Reference for the GET /inboxes/events endpoint in the BillionSend
    API.
sidebar:
  label: Stream inbox events
  badge: GET
title: Stream inbox events
type: openapi-operation
---
BillionSend extension: a server-sent event stream of every inbox event of the team, named like the webhook events (inbox.email.received, inbox.thread.created, email.received, …; types narrows them), each carrying the webhook payload's data. Send the key as a Bearer header; the stream stays open, and a client that reconnects with Last-Event-ID resumes without losing events. Needs a team-wide key: a key held to one domain streams one inbox at a time. An agent (an inbox-scoped key, or an MCP connection) never receives the events about held mail (inbox.email.quarantined), replay included, and naming them in types is a 403. A stream closes within a few seconds once its key is revoked, its person leaves the team or its inbox is gone; it is also closed every ten minutes or so, and the client reconnects with Last-Event-ID. Streams are capped per key and per team on each API process (429 too_many_streams).

`GET /inboxes/events`

**Responses**

- `200` — An event stream that stays open. A client that reconnects with Last-Event-ID gets the events it missed (up to 24 hours back, then a stream.gap event) before the live ones
- `401` — Missing, malformed, unknown or revoked API key
- `403` — A key held to one domain or one inbox, or an agent naming an event about held mail
- `422` — Validation error
- `429` — Too many streams open, or the rate limit (rate\_limit\_exceeded, with Retry-After)

Response example, 200:

```json
"string"
```
