Mailboxes

Create a mailbox

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.

post/mailboxes

Request

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

Headers

Idempotency-Keystring required

A unique key (e.g. a UUID) that makes this write safe to retry. Reusing a key returns the original result; reusing it with a different body returns 409.

Request body

email_addressstring email required

The mailbox email address.

smtp_hoststring required

SMTP server hostname, e.g. smtp.gmail.com.

smtp_portinteger

SMTP port. One of 25, 465, 587. Defaults to 587.

smtp_usernamestring required

SMTP login (usually the email address).

smtp_passwordstring password required

SMTP password or app password.

imap_hoststring required

IMAP server hostname, e.g. imap.gmail.com.

imap_portinteger

IMAP port. One of 143, 993. Defaults to 993.

imap_usernamestring required

IMAP login (usually the email address).

imap_passwordstring password required

IMAP password or app password.

external_idstring

Your own reference id for this mailbox (unique per workspace).

display_namestring

Display name shown on outgoing mail.

sending_enabledboolean

Whether the mailbox may send. Defaults to true.

daily_send_limitinteger

Max sends per day. Defaults to 50.

auto_enable_warmupboolean

Enable warmup automatically once the connection test passes.

Response

Success

Changes

No recorded changes to this operation across all 1 revision of this API.