Sign in
Mailboxes

Create a mailbox

Changed on

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

Request

  • Base URL: https://app.sendmux.ai/api/v1
  • URL: https://app.sendmux.ai/api/v1/mailboxes
  • Auth: one of:
    • HTTP bearer
    • OAuth 2 (authorization code, authorization URL https://app.sendmux.ai/oauth/authorize, token URL https://app.sendmux.ai/oauth/token, scopes: mailbox.admin.create)

Headers

Idempotency-Keystring

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.

Example:mailboxes-create-20260424-001

Request body

display_namestring

Optional display name shown in outbound From headers.

emailstring required

Mailbox email address to create.

quota_bytesinteger

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

Example request

{
  "quota_bytes": 5368709120
}

Response

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

oktrue required

Example response

{
  "meta": {
    "request_id": "req_clxxxxxxxxxxxxxxxxxxxxxxxxx"
  },
  "data": {
    "credential": {
      "imap_port": 993,
      "public_id": "smx_clxxxxxxxxxxxxxxxxxxxxxxxxx",
      "server": "mail.sendmux.ai",
      "smtp_port": 587
    },
    "mailbox": {
      "email": "agent@acme.com",
      "id": "mbx_clxxxxxxxxxxxxxxxxxxxxxxxxx",
      "status": "active"
    }
  }
}

Changes

  • b42ce87003aeRevision changes
    • breaking

      the // response's property type changed from object null to no type for status

    • breaking

      removed the required property /// from the response with the status

    • breaking

      removed the required property /// from the response with the status

    • breaking

      removed the required property /// from the response with the status

    • breaking

      removed the required property /// from the response with the status

    • breaking

      removed the required property /// from the response with the status

    • breaking

      removed the required property /// from the response with the status

    • breaking

      removed the required property /// from the response with the status

    • breaking

      removed the required property /// from the response with the status

    • info

      added subschema #2 to the // response property anyOf list for the response status

  • 7807ce923952Revision changes
    • info

      the endpoint scheme security oauth2 was added to the API