# list_inboxes

Behavior, inputs, outputs and permissions for list_inboxes.

Source: https://docs.getridian.com/developers/tools/list_inboxes/
Language: en
Reviewed: 2026-10-06

This reference is generated from the published tool contract.

## Behavior and boundaries

Lists Agent Mailboxes selected for this client in the current workspace. Does not list Google or Microsoft mail accounts. Returns mailbox IDs, names, addresses, whether receiving is enabled, and a managementUrl for console-only whole-mailbox deletion. allowance reports this person’s current plan, workspace limit/used/remaining, canCreate, blockedReason and retryAt (timestamp in milliseconds or null). Usage counts all own non-deleted workspace mailboxes, including disabled or client-excluded ones. Free admission also checks the person-wide free slot; rate limits span workspaces. remaining is arithmetic workspace capacity, not a creation promise; use canCreate and blockedReason. No other workspace identifiers or message content are read out.

## Permissions

Granted scopes, accounts, calendars and visibility rules limit access. Workspace administrators do not automatically gain access to other users’ accounts.

`inbox:read`

[Consent and boundaries](https://docs.getridian.com/developers/authentication/)

## Input

```json
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {},
  "additionalProperties": false
}
```

## Output

```json
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "allowance": {
      "type": "object",
      "properties": {
        "plan": {
          "type": "string",
          "enum": [
            "free",
            "basic",
            "professional"
          ]
        },
        "limit": {
          "type": "number"
        },
        "used": {
          "type": "number"
        },
        "remaining": {
          "type": "number"
        },
        "canCreate": {
          "type": "boolean"
        },
        "blockedReason": {
          "anyOf": [
            {
              "type": "string",
              "enum": [
                "INBOX_MAILBOX_LIMIT",
                "INBOX_FREE_MAILBOX_LIMIT",
                "INBOX_CREATION_RATE_LIMIT",
                "INBOX_CLIENT_ACCESS_DENIED"
              ]
            },
            {
              "type": "null"
            }
          ]
        },
        "retryAt": {
          "type": [
            "number",
            "null"
          ]
        }
      },
      "required": [
        "plan",
        "limit",
        "used",
        "remaining",
        "canCreate",
        "blockedReason",
        "retryAt"
      ],
      "additionalProperties": false
    },
    "managementUrl": {
      "type": "string"
    },
    "mailboxes": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "minLength": 1,
            "maxLength": 200
          },
          "name": {
            "type": "string"
          },
          "address": {
            "type": "string"
          },
          "enabled": {
            "type": "boolean"
          },
          "canManage": {
            "type": "boolean"
          }
        },
        "required": [
          "id",
          "name",
          "address",
          "enabled",
          "canManage"
        ],
        "additionalProperties": false
      }
    }
  },
  "required": [
    "allowance",
    "managementUrl",
    "mailboxes"
  ],
  "additionalProperties": false
}
```

## Errors and retries

Check the tool result for errors. Do not blindly retry writes after a timeout. Check the current resource or send status first.

[Error handling](https://docs.getridian.com/developers/errors/)