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

# Create a mailbox

`POST /mailboxes`

## Request

- Base URL: `https://faivelo.com/api/v1`
- URL: `https://faivelo.com/api/v1/mailboxes`
- Auth: HTTP bearer

Creates a new mailbox and returns IMAP/SMTP credentials. The password is shown **only once** in this response. Requires scope `mailboxes:write`. Limited to **10 mailboxes per key per rolling 24h**. When called with an **agent** key, the new mailbox is automatically granted to that key.

## Request body

- CreateMailboxRequest: Request body for creating a mailbox
  - `domain` string, required
  - `localPart` string, required: The part before the @. 1–64 chars, alphanumeric plus `._%+-`.
  - `password` string: Optional; a secure password is generated if omitted. 8 to 128 characters.
  - `displayName` string: Display name for the mailbox (max 128 chars)

## Response `200`

Mailbox created with credentials

- object
  - `success` boolean
  - `data` MailboxWithCredentials: Newly created mailbox with one-time credentials
    - `id` string
    - `localPart` string
    - `fullAddress` string
    - `displayName` string, nullable
    - `active` boolean
    - `createdAt` string, date-time
    - `credentials` Credentials: IMAP/SMTP connection credentials
      - `imapServer` string
      - `imapPort` integer
      - `smtpServer` string
      - `smtpPort` integer
      - `username` string
      - `password` string, nullable: The generated password, shown once. `null` when you chose the password yourself (a reset with `password`, or a partner create with one).
      - `ssl` boolean

## Other responses

- `401`: Missing or invalid API key
- `402`: The account's plan does not include the API (`plan_required`)
- `403`: The key lacks the required scope
- `409`: Mailbox already exists
- `429`: Rate limit exceeded

---

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