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

# Create a mailbox

`POST /v1/mailboxes`

## Request

- Base URL: `https://api.samva.dev`
- URL: `https://api.samva.dev/v1/mailboxes`
- Auth: API key in header `x-api-key`

Creates a mailbox with one endpoint and returns it with status 201; the caller gets an admin grant on it. An email endpoint's address must be under the organization's Samva-hosted mail domain or a verified domain with receiving enabled, and the mailbox sends from it. A phone endpoint's address is a number the organization connected on that channel, in E.164 form. The slug defaults to the address's local part, or a phone number's digits. Pass `slug` when that is taken or not a valid slug. The mailbox receives mail from now on; mail that arrived earlier is not added to it. Conflicts if the address or slug is already in use. Returns 402 when the organization is at its plan's mailbox allowance or at its mailbox storage allowance; incoming mail is still received past the storage allowance.

## Request body

- CreateMailboxPayload
  - `namespaceId` string
  - `endpoint` CreateMailboxEndpointPayload, required
    - `channel` 'email', required: The channel an endpoint, thread, or message belongs to.
    - `address` string, required
    - `displayName` string, nullable
  - `name` string, required
  - `slug` string, nullable
  - `metadata` MailboxMetadata

## Response `201`

Success

- Mailbox
  - `id` string, required
  - `namespaceId` string, required
  - `slug` string, required
  - `name` string, required
  - `status` 'active' | 'paused', required
  - `primaryAddress` string, nullable, required
  - `createdAt` string, required
  - `description` string, nullable, required
  - `metadata` MailboxMetadata, required
  - `endpoints` MailboxEndpoint[], required
    - `id` string, required
    - `address` string, required
    - `displayName` string, nullable, required
    - `default` boolean, required
    - `channel` 'email', required
    - `source` 'samvaHosted' | 'verifiedDomain', required
    - `domainId` string, nullable, required
  - `updatedAt` string, required

## Other responses

- `401`: UnauthorizedError
- `402`: PaymentRequiredError
- `403`: FlagDisabledError | ForbiddenError
- `404`: ResourceNotFoundError
- `409`: ConflictError
- `422`: ValidationError
- `500`: InternalError
- `502`: BillingProviderError
- `504`: GatewayTimeoutError

---

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