---
title: "Create a mailbox"
method: POST
path: "/api/v1/mailboxes"
tags: ["mailboxes"]
---

# Create a mailbox

`POST /api/v1/mailboxes`

## Request

- Base URL: `https://postfleet.ai`
- URL: `https://postfleet.ai/api/v1/mailboxes`
- Auth: HTTP bearer

Provisions a mailbox. Account-plane: a mailbox-bound key is rejected (`code:key_scope`). Accepts `bootstrap`, `api`, or `mcp` scope. Without `domain_id` the address is `agent-{slug}@{shared-domain}`; with a verified `domain_id` (paid plan) it is `{slug}@{your-domain}`.

## Request body

- CreateMailboxRequest
  - `slug` string: Local-part slug, `[a-z0-9][a-z0-9-]{0,40}`. Random hex if omitted.
  - `display_name` string
  - `extraction_schema_id` string: Must belong to this account.
  - `domain_id` string: A verified custom domain (paid plan). Omit to use the shared domain.

## Response `201`

Mailbox created.

- object
  - `id` string, required
  - `address` string, required

## Other responses

- `400`: Invalid `slug`, or the referenced domain is not verified.
- `401`: Missing or invalid bearer token, or a key whose scope is not permitted for this endpoint.
- `403`: Mailbox-bound key on an account-plane route (`code:key_scope`), the account is at its plan mailbox limit (`code:mailbox_limit`), or custom domains require a paid plan.
- `404`: Referenced `extraction_schema_id` or `domain_id` not found for this account.

---

[API](https://skmtc.dev/postfleet/apis/postfleet-api.md) · [All operations](https://skmtc.dev/postfleet/apis/postfleet-api/llms.txt) · [OpenAPI document](https://skmtc.dev/postfleet/apis/postfleet-api/revisions/bae1dabfa89e?raw)