---
title: "Provision a new mailbox"
method: POST
path: "/v1/mailboxes"
tags: ["mailboxes"]
---

# Provision a new mailbox

`POST /v1/mailboxes`

## Request

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

Creates the mailbox row, seeds its default policy, and provisions the
domain/user/mailbox in Stalwart, all inside one transaction — a
Stalwart provisioning failure rolls back the DB row. Subject to the
account tier's mailbox limit.

## Request body

- object
  - `description` string, nullable
  - `domain_id` integer, required
  - `email_local_part` string, nullable: Local part of the mailbox address. Lowercased; must be 1-64 chars of alphanumerics, `.`, `-`, `_`. Falls back to a normalised form of `name` when omitted or invalid.
  - `name` string, required

## Response `200`

Mailbox created.

- MailboxRecord
  - `created_at` string, date-time, required
  - `description` string, nullable
  - `domain_id` integer, required
  - `email_address` string, required
  - `id` integer, required
  - `is_active` boolean, required
  - `name` string, required
  - `updated_at` string, date-time, required
  - `user_id` integer, required

## Other responses

- `400`: Invalid domain id, domain not owned by caller, domain not verified, or no usable email handle could be derived.
- `401`: Missing or invalid credential, raised by the `ApiKeyAuth` extractor (`backend/src/api_keys.rs`) before the handler runs: no `Authorization` header, a non-`Bearer` scheme, a key that doesn't hash-match any row, or a key whose status isn't `active`. A header that isn't valid UTF-8, has no scheme token, or has `Bearer` with no key value returns 400 with this same JSON shape instead of 401.
- `403`: Account's mailbox limit reached.
- `409`: The derived email address is already in use.
- `500`: Database error (tier lookup, count, insert, policy seed, transaction).
- `502`: Stalwart domain/user/mailbox provisioning failed; the DB transaction was rolled back.

---

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