Create a mailbox

curl --request POST \
  --url https://app.sendmux.ai/api/v1/mailboxes \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "email": "<string>"
}
'

{
  "ok": true,
  "meta": {
    "request_id": "req_clxxxxxxxxxxxxxxxxxxxxxxxxx"
  },
  "data": {
    "mailbox": {
      "id": "mbx_clxxxxxxxxxxxxxxxxxxxxxxxxx",
      "email": "agent@acme.com",
      "display_name": "<string>",
      "quota_bytes": 123,
      "send_scope": {
        "provider_public_ids": [
          "<string>"
        ],
        "group_public_ids": [
          "<string>"
        ]
      },
      "status": "active",
      "created_at": "<string>"
    },
    "credential": {
      "public_id": "smx_clxxxxxxxxxxxxxxxxxxxxxxxxx",
      "secret": "<string>",
      "key_prefix": "<string>",
      "key_suffix": "<string>",
      "server": "mail.sendmux.ai",
      "imap_port": 993,
      "smtp_port": 587,
      "username": "<string>"
    },
    "warning": "<string>"
  }
}

Mailboxes

Create a mailbox

Provisions a new mailbox plus an initial bearer token and matching IMAP/SMTP mailbox password. The domain portion of the email must already be verified via POST /domains. If supplied, quota_bytes must be one of the current storage tiers: 1073741824 (1 GB), 5368709120 (5 GB), or 53687091200 (50 GB). Creation provisions resources on our mail platform and, for @myagent.mx addresses, on Amazon SES — any failure rolls the partial state back automatically.

Supply an Idempotency-Key header (any unique string, max 255 chars) to safely retry on network errors. Replays with the same key return the original response; replays with a different body return 409 idempotency_conflict.

POST

/

mailboxes

Create a mailbox

curl --request POST \
  --url https://app.sendmux.ai/api/v1/mailboxes \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "email": "<string>"
}
'

{
  "ok": true,
  "meta": {
    "request_id": "req_clxxxxxxxxxxxxxxxxxxxxxxxxx"
  },
  "data": {
    "mailbox": {
      "id": "mbx_clxxxxxxxxxxxxxxxxxxxxxxxxx",
      "email": "agent@acme.com",
      "display_name": "<string>",
      "quota_bytes": 123,
      "send_scope": {
        "provider_public_ids": [
          "<string>"
        ],
        "group_public_ids": [
          "<string>"
        ]
      },
      "status": "active",
      "created_at": "<string>"
    },
    "credential": {
      "public_id": "smx_clxxxxxxxxxxxxxxxxxxxxxxxxx",
      "secret": "<string>",
      "key_prefix": "<string>",
      "key_suffix": "<string>",
      "server": "mail.sendmux.ai",
      "imap_port": 993,
      "smtp_port": 587,
      "username": "<string>"
    },
    "warning": "<string>"
  }
}

Authorizations

Authorization

string

header

required

Sendmux API key. Use a root API key for Management API routes, or a mailbox credential for Mailbox API routes. Obtain keys from the dashboard under API Keys.

Headers

Idempotency-Key

string

Client-chosen unique key to safely retry the request. Cached for 24h per (team, endpoint, key). Different body with same key returns 409 idempotency_conflict.

Maximum string length: 255

Example:

"mailboxes-create-20260424-001"

Body

application/json

email

string

required

Required string length: 5 - 254

display_name

string

Required string length: 1 - 254

quota_bytes

integer

Storage quota in bytes. Allowed values: 1073741824 (1 GB), 5368709120 (5 GB), 53687091200 (50 GB).

Required range: x >= 1

Example:

5368709120

send_scope

object

Hide child attributes

send_scope.type

enum<string>

required

Available options:

all,

providers,

group

send_scope.provider_public_ids

string[]

Required string length: 1 - 128

send_scope.group_public_ids

string[]

Required string length: 1 - 128

Response

Mailbox created. The response carries a Location header pointing at the canonical GET URL for the new mailbox.

ok

enum<boolean>

required

Available options:

true

meta

object

required

Hide child attributes

meta.request_id

string

required

Example:

"req_clxxxxxxxxxxxxxxxxxxxxxxxxx"

data

object

required

Hide child attributes

data.mailbox

object

required

Hide child attributes

data.mailbox.id

string

required

Public ID

Example:

"mbx_clxxxxxxxxxxxxxxxxxxxxxxxxx"

data.mailbox.email

string

required

Mailbox email address (lowercase)

Example:

"agent@acme.com"

data.mailbox.display_name

string | null

required

Optional display name shown in outbound From headers

data.mailbox.quota_bytes

integer | null

required

Storage quota in bytes. Current writable tiers are 1 GB, 5 GB, and 50 GB.

data.mailbox.send_scope

object

required

Hide child attributes

data.mailbox.send_scope.type

enum<string>

required

Outbound routing strategy. all lets the mailbox use any team-configured provider; providers restricts to the listed provider IDs; group routes via a delivery group.

Available options:

all,

providers,

group

data.mailbox.send_scope.provider_public_ids

string[]

Provider public IDs (only when type=providers)

data.mailbox.send_scope.group_public_ids

string[]

Delivery group public IDs (only when type=group)

data.mailbox.status

string

required

active | suspended | deleted

Example:

"active"

data.mailbox.created_at

string

required

ISO 8601 creation timestamp

data.credential

object

required

Initial credential for the mailbox. null if credential generation failed — call POST /mailboxes/{id}/keys to retry.

Hide child attributes

data.credential.public_id

string

required

Credential public ID

Example:

"smx_clxxxxxxxxxxxxxxxxxxxxxxxxx"

data.credential.secret

string

required

Mailbox credential — shown exactly once. Use as a Bearer token on the HTTP API and as the password for IMAP retrieval and SMTP submission.

data.credential.key_prefix

string

required

data.credential.key_suffix

string

required

data.credential.server

string

required

Mailbox server name

Example:

"mail.sendmux.ai"

data.credential.imap_port

integer

required

IMAP retrieval port

Example:

993

data.credential.smtp_port

integer

required

SMTP submission port

Example:

587

data.credential.username

string

required

Mailbox email address used as the login

data.warning

string | null

required

Optional warning string when the mailbox was created without an initial credential