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

# Create a mailbox

`POST /mailboxes`

## Request

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

Adds a mailbox and runs an asynchronous connection test (status moves created → testing → connected or error). If the email matches a previously soft-deleted mailbox, that mailbox is restored instead and the response is 200 with its preserved warmup history (otherwise 201).

Required scope: `mailboxes:write`.

Requires a unique `Idempotency-Key` request header so retries never duplicate.

Send a unique Idempotency-Key header so retries never create duplicates.

Connection test runs in the background — poll GET /mailboxes/{id} until status is "connected".

A newly created mailbox reports read_channel_state "not_tested" until we have actually opened its inbox. That is not a failure — it means we have no evidence either way yet, so do not treat it as confirmation that replies will be seen. The state turns "ok" once we complete a read of the inbox; we read every connected mailbox on a regular cycle whether or not warmup is on, and read_channel_verified_at shows when the latest completed read happened.

## Headers

- `Idempotency-Key` string, required

## Request body

- object
  - `email_address` string, email, required: The mailbox email address.
  - `smtp_host` string, required: SMTP server hostname, e.g. smtp.gmail.com.
  - `smtp_port` integer: SMTP port. One of 25, 465, 587. Defaults to 587.
  - `smtp_username` string, required: SMTP login (usually the email address).
  - `smtp_password` string, password, required: SMTP password or app password.
  - `imap_host` string, required: IMAP server hostname, e.g. imap.gmail.com.
  - `imap_port` integer: IMAP port. One of 143, 993. Defaults to 993.
  - `imap_username` string, required: IMAP login (usually the email address).
  - `imap_password` string, password, required: IMAP password or app password.
  - `external_id` string: Your own reference id for this mailbox (unique per workspace).
  - `display_name` string: Display name shown on outgoing mail.
  - `sending_enabled` boolean: Whether the mailbox may send. Defaults to true.
  - `daily_send_limit` integer: Max sends per day. Defaults to 50.
  - `auto_enable_warmup` boolean: Enable warmup automatically once the connection test passes.

## Response `201`

Success

## Other responses

- `400`: `validation_error` — Body failed validation.
- `401`: `unauthorized` — Missing or invalid API key.
- `403`: `mailbox_limit_exceeded` — At or above your plan's mailbox limit.; `insufficient_scope` — The API key lacks the scope this endpoint requires.
- `409`: `duplicate_email` — An active mailbox already uses this email.; `duplicate_external_id` — The external_id is already in use.
- `422`: `ssrf_blocked` — A host resolved to a private/internal IP.; `invalid_port` — A port outside the allowed list (25/465/587/143/993).
- `429`: `rate_limited` — Too many requests — slow down and retry after the Retry-After delay.

---

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