# create_inbox

Behavior, inputs, outputs and permissions for create_inbox.

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

This reference is generated from the published tool contract.

## Behavior and boundaries

Creates an Agent Mailbox on Ridian's configured mail domain. Requires client permission for all current and future Agent Mailboxes and an available mailbox slot. Free allows one mailbox per person across workspaces; paid allowances remain per workspace. At most 20 successful creations per person in a rolling 24 hours across all workspaces and clients; deleting a mailbox does not reset this limit. localPart is 3–40 lowercase letters, digits or hyphens; reserved or previously used addresses are unavailable. Returns its ID, full email address and a managementUrl for the mailbox in Ridian. Does not start an agent or send mail. After an uncertain result, list_inboxes before retrying with a different address.

## Permissions

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

`inbox:manage`

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

## Input

```json
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "name": {
      "type": "string",
      "minLength": 1,
      "maxLength": 80
    },
    "localPart": {
      "type": "string",
      "pattern": "^[a-z0-9][a-z0-9-]{2,39}$"
    }
  },
  "required": [
    "name",
    "localPart"
  ],
  "additionalProperties": false
}
```

## Output

```json
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "minLength": 1,
      "maxLength": 200
    },
    "address": {
      "type": "string"
    },
    "managementUrl": {
      "type": "string"
    }
  },
  "required": [
    "id",
    "address",
    "managementUrl"
  ],
  "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/)