---
title: "List inboxes you can query"
method: GET
path: "/api/inboxes"
tags: ["Inboxes"]
---

# List inboxes you can query

`GET /api/inboxes`

## Request

- Base URL: `https://core-api.getaptly.com`
- URL: `https://core-api.getaptly.com/api/inboxes`
- Auth: one of:
  - API key in header `x-token`
  - API key in header `Authorization`
  - HTTP bearer
- TypeScript: <https://skmtc.dev/getaptly/apis/aptly-api/docs/api/inboxes/get.ts> (a function with typed inputs; its response is checked against the schema)

Returns the email and phone/SMS inboxes available to the credential, for use
as the `channelId` on the messages and analytics endpoints.

With delegate-token auth (`inboxes:*` scope) results are limited to
inboxes the authenticated user can reach, and each entry carries `access`:
`owned` when the user is a member of the inbox (directly or through a team),
`monitored` when it is another user's private inbox that the caller is
permitted to monitor. `scope` filters on that value.

Monitoring requires the `conversations.monitor_admin` permission on the
caller and `conversations.monitor_access` on the inbox owner's role, so a
caller without those permissions sees only `owned` inboxes.

API keys and partner tokens are company-scoped and carry no user identity, so
they return every inbox in the company, omit `access`, and reject `scope`
with a `400`.

## Query parameters

- `scope` 'owned' | 'monitored' | 'all'

## Response `200`

Inboxes available to the credential.

- object
  - `data` object[]
    - `channelId` string: External channel meta ID (`meta.id`). Use this on the other inbox endpoints.
    - `type` 'email' | 'phone'
    - `provider` string, nullable: Underlying provider, e.g. `gmail`, `office365`, `twilio`.
    - `name` string, nullable
    - `email` string, nullable: Set for email inboxes.
    - `number` string, nullable: Set for phone/SMS inboxes.
    - `isShared` boolean
    - `access` 'owned' | 'monitored': Present only with delegate-token auth. `owned` = the user is a member of the inbox; `monitored` = another user's private inbox the caller may monitor.

## Other responses

- `400`: Invalid `scope`, or `scope` used with a company-scoped credential.
- `401`: Invalid or missing credential.

---

[API](https://skmtc.dev/getaptly/apis/aptly-api.md) - [All operations](https://skmtc.dev/getaptly/apis/aptly-api/llms.txt) - [OpenAPI document](https://skmtc.dev/getaptly/apis/aptly-api/revisions/75c367e0b8e5?raw)