---
title: "Add mailboxes"
method: POST
path: "/api/v1/mailboxes"
tags: ["Mailboxes"]
---

# Add mailboxes

`POST /api/v1/mailboxes`

## Request

- Base URL: `https://api.aerosend.io`
- URL: `https://api.aerosend.io/api/v1/mailboxes`
- Auth: API key in header `X-API-Key`

Adds one or more mailboxes for the authenticated client.

## Email Validation
- Email format is validated (must be valid RFC format)
- Email is automatically normalized (lowercase)

## Domain Validation
- Domain must exist and belong to the authenticated client
- Mailboxes can be added when the domain is `pending`, `in_progress`, or `active`
- Only `inactive` domains are rejected
- Missing domain names are returned in the error
- `inactive` domain names are returned in the error (`DOMAIN_INACTIVE`)

## Mailbox Limits
- Maximum mailboxes per domain: 3
- If limit would be exceeded, error is returned with details

## Duplicate Check
- Email addresses must be unique within a domain
- If duplicates exist, all duplicate emails are returned in the error

## Default Settings
- All new mailboxes have status set to `pending`

## Request body

- AddMailboxesRequest: Request to add one or more mailboxes
  - `mailboxes` AddMailboxItem[], required: List of mailboxes to add. Maximum 60 mailboxes per request.
    - `email` string, email, required: Email address for the mailbox. Domain will be extracted automatically from the email.
    - `first_name` string, required: First name of the mailbox owner
    - `last_name` string, required: Last name of the mailbox owner

## Response `201`

Mailboxes added successfully

- AddMailboxesApiResponse
  - `success` boolean: Success flag
  - `data` AddMailboxesResponse: Response after adding mailboxes
    - `added_count` integer: Number of mailboxes successfully added
    - `mailboxes` MailboxSummary[]: List of added mailbox details
      - `id` integer: Mailbox ID
      - `email` string: Email address
      - `domain_id` integer: Domain ID
      - `status` string: Mailbox status
  - `timestamp` string: Response timestamp

## Other responses

- `400`: Invalid request - validation error or invalid email format
- `401`: Unauthorized - Invalid or expired API key
- `404`: Domain not found
- `409`: Conflict - Duplicate email, mailbox limit exceeded, or domain inactive
- `429`: Rate limit exceeded

---

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