# List temporary inboxes

`GET /v1/inboxes`

- Authentication: required (Bearer token)
- Required scope: `api.inboxes.view`

The inboxes this credential can see, newest first.

`scope` defaults to `own` — only what this credential minted. `org`
adds the inboxes colleagues have marked org-visible. `all` asks for
every inbox in the org including private ones; a caller without the
`inboxes.manage_all` dashboard permission is silently narrowed to
`org` rather than refused, so asking for more than you may see returns
what you may see.

Unpaginated. An org holds at most 25 live inboxes, `limit` bounds how
far back the expired ones go, and the standard `{data, pagination}`
envelope is still returned so this parses like every other collection
here. `pagination.has_more` is always `false`.

Message content is never in this response — only counters. Read the
mail at `GET /v1/inboxes/{id}/messages`.

## Query parameters

- `scope` (string enum, optional) — Whose inboxes to return. `own` (default), `org`, or `all`. An unknown value is 422, not an empty page.
- `status` (string enum, optional) — Narrow to one lifecycle state. Omit for all of them. An unknown value is 422.
- `account_ref` (string, optional) — Narrow to the inboxes minted with exactly this `account_ref` — the partition key you sent at mint. EXACT MATCH, case-sensitive, no trimming: `WS_123` does not match `ws_123`. Combined with `scope` and `status` rather than replacing them, so this still only returns what your credential may see. An unknown value is an empty page, not an error, because SendOps does not know which of your keys exist.
- `limit` (integer, optional) — Page size (1–200). Default 50.

## Example request

```bash
curl 'https://api.sendops.dev/v1/inboxes' \
  -H "Authorization: Bearer $SENDOPS_API_KEY"
```

## Responses

### 200 — The inboxes visible to this credential

Content type: `application/json`

```json
{
  "data": [
    {
      "id": "00000000-0000-0000-0000-000000000000",
      "address": "k7q2m9xv4p@sndps.com",
      "expires_at": "2026-05-17T20:00:00Z",
      "poll_url": "https://example.com",
      "pull_url": "https://fetch.sendops.dev/p/pt_ab3k…/messages",
      "pull_token": {
        "id": "00000000-0000-0000-0000-000000000000",
        "prefix": "pt_ab3kd9",
        "label": "string",
        "created_at": "2026-05-17T20:00:00Z",
        "revoked_at": "2026-05-17T20:00:00Z"
      },
      "restricted": true,
      "restriction_source": "verified",
      "account_ref": "ws_123",
      "visibility": "private",
      "label": "string",
      "status": "active",
      "allowed_senders": [
        "string"
      ],
      "message_count": 0,
      "dropped_count": 0,
      "created_at": "2026-05-17T20:00:00Z"
    }
  ],
  "pagination": {
    "has_more": true,
    "next_cursor": "string"
  }
}
```

### 401 — Missing, malformed, or unknown API key

Content type: `application/problem+json`

```json
{
  "type": "https://example.com",
  "title": "string",
  "status": 0,
  "detail": "string",
  "code": "invalid_key",
  "request_id": "string",
  "retry_after": 0,
  "retention_days": 0,
  "scope": "string",
  "resource": "string",
  "errors": [
    {
      "field": "string",
      "reason": "string"
    }
  ],
  "attribute_id": "00000000-0000-0000-0000-000000000000",
  "content_hash": "string",
  "differs": [
    "string"
  ]
}
```

### 403 — Key lacks the required scope or plan limit violated

Content type: `application/problem+json`

```json
{
  "type": "https://example.com",
  "title": "string",
  "status": 0,
  "detail": "string",
  "code": "invalid_key",
  "request_id": "string",
  "retry_after": 0,
  "retention_days": 0,
  "scope": "string",
  "resource": "string",
  "errors": [
    {
      "field": "string",
      "reason": "string"
    }
  ],
  "attribute_id": "00000000-0000-0000-0000-000000000000",
  "content_hash": "string",
  "differs": [
    "string"
  ]
}
```

### 422 — A query parameter, path value or body field failed validation.

The body is a `validation_failed` Problem. When the refusal is about a
reference — a segment key, template slug, topic or attribute name the
organization does not have — it additionally carries `validation_code`,
`field`, `line`/`column`, `missing`, `candidates` and `next_step`, so a
client can correct the call without a second round of guessing. See
`ValidationProblem`.

Content type: `application/problem+json`

```json
{
  "type": "https://example.com",
  "title": "string",
  "status": 0,
  "detail": "string",
  "code": "invalid_key",
  "request_id": "string",
  "retry_after": 0,
  "retention_days": 0,
  "scope": "string",
  "resource": "string",
  "errors": [
    {
      "field": "string",
      "reason": "string"
    }
  ],
  "attribute_id": "00000000-0000-0000-0000-000000000000",
  "content_hash": "string",
  "differs": [
    "string"
  ],
  "validation_code": "invalid_syntax",
  "field": "string",
  "line": 0,
  "column": 0,
  "missing": [
    {
      "kind": "segment",
      "key": "string"
    }
  ],
  "candidates": {},
  "next_step": "string"
}
```

### 429 — Per-org rate limit exceeded

Content type: `application/problem+json`

```json
{
  "type": "https://example.com",
  "title": "string",
  "status": 0,
  "detail": "string",
  "code": "invalid_key",
  "request_id": "string",
  "retry_after": 0,
  "retention_days": 0,
  "scope": "string",
  "resource": "string",
  "errors": [
    {
      "field": "string",
      "reason": "string"
    }
  ],
  "attribute_id": "00000000-0000-0000-0000-000000000000",
  "content_hash": "string",
  "differs": [
    "string"
  ]
}
```

### 500 — Unexpected server-side failure. The `code` is `internal_error`. The
`request_id` field can be quoted to SendOps support to investigate.

Content type: `application/problem+json`

```json
{
  "type": "https://example.com",
  "title": "string",
  "status": 0,
  "detail": "string",
  "code": "invalid_key",
  "request_id": "string",
  "retry_after": 0,
  "retention_days": 0,
  "scope": "string",
  "resource": "string",
  "errors": [
    {
      "field": "string",
      "reason": "string"
    }
  ],
  "attribute_id": "00000000-0000-0000-0000-000000000000",
  "content_hash": "string",
  "differs": [
    "string"
  ]
}
```