> ## Documentation Index > Fetch the complete documentation index at: https://sendmux.ai/docs/llms.txt > Use this file to discover all available pages before exploring further. # 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`. ## OpenAPI ````yaml /openapi-app.json post /mailboxes openapi: 3.1.0 info: description: Programmatic access to your Sendmux email infrastructure. title: Sendmux API version: 1.0.0 servers: - description: API v1 url: https://app.sendmux.ai/api/v1 security: - bearerAuth: [] paths: /mailboxes: post: tags: - Mailboxes summary: Create a mailbox description: >- 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`. operationId: managementCreateMailbox parameters: - in: header name: Idempotency-Key required: false schema: description: >- 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 maxLength: 255 type: string requestBody: content: application/json: schema: additionalProperties: false properties: display_name: description: Optional display name shown in outbound From headers. maxLength: 254 minLength: 1 type: string email: description: Mailbox email address to create. maxLength: 254 minLength: 5 type: string quota_bytes: description: >- Storage quota in bytes. Allowed values: 1073741824 (1 GB), 5368709120 (5 GB), 53687091200 (50 GB). example: 5368709120 minimum: 1 type: integer send_scope: additionalProperties: false description: Optional outbound routing restrictions. properties: group_public_ids: description: >- Delivery group public IDs allowed for sending when type is `group`. items: maxLength: 128 minLength: 1 type: string type: array provider_public_ids: description: >- Provider public IDs allowed for sending when type is `providers`. items: maxLength: 128 minLength: 1 type: string type: array type: description: >- Outbound routing strategy. Use `providers` with provider_public_ids, or `group` with group_public_ids. enum: - all - providers - group type: string required: - type type: object required: - email type: object responses: '201': content: application/json: schema: $ref: '#/components/schemas/MailboxCreateResultResponse' description: >- Mailbox created. The response carries a `Location` header pointing at the canonical GET URL for the new mailbox. headers: Location: description: Canonical GET URL for the newly created mailbox. schema: example: /api/v1/mailboxes/mx_clxxxxxxxxxxxxxxxxxxxxxxxxx type: string '400': content: application/json: schema: $ref: '#/components/schemas/ApiError' description: Invalid request body '409': content: application/json: schema: $ref: '#/components/schemas/ApiError' description: >- Email already in use (error code `conflict`), or `Idempotency-Key` was replayed with a different body (`idempotency_conflict`). '413': content: application/json: schema: $ref: '#/components/schemas/ApiError' description: Request body too large '422': content: application/json: schema: $ref: '#/components/schemas/ApiError' description: Domain not yet verified or semantic validation failure '503': content: application/json: schema: $ref: '#/components/schemas/ApiError' description: Team is not yet provisioned for sending security: - bearerAuth: [] components: schemas: MailboxCreateResultResponse: allOf: - $ref: '#/components/schemas/SuccessEnvelope' - properties: data: $ref: '#/components/schemas/MailboxCreateResult' meta: $ref: '#/components/schemas/ResponseMeta' required: - data type: object unevaluatedProperties: false ApiError: additionalProperties: false properties: error: additionalProperties: false properties: code: description: Machine-readable error code enum: - invalid_parameter - missing_parameter - authentication_required - insufficient_permissions - not_found - conflict - limit_exceeded - idempotency_conflict - payload_too_large - validation_error - rate_limit_exceeded - service_unavailable - internal_error example: invalid_parameter type: string doc_url: description: Link to relevant documentation type: string errors: description: >- Accumulated per-field issues for validation errors. Only present on 400/422 responses. items: $ref: '#/components/schemas/ApiErrorDetail' type: array message: description: Human-readable error description type: string param: description: The parameter that caused the error type: string retryable: description: >- Whether the caller may safely retry this request. 4xx are typically false (except 429); 5xx are typically true. example: false type: boolean required: - code - message - retryable type: object meta: additionalProperties: false properties: request_id: example: req_clxxxxxxxxxxxxxxxxxxxxxxxxx type: string required: - request_id type: object ok: enum: - false type: boolean required: - ok - error - meta type: object SuccessEnvelope: properties: meta: additionalProperties: {} properties: {} type: object ok: enum: - true type: boolean required: - ok - meta type: object MailboxCreateResult: additionalProperties: false properties: credential: $ref: '#/components/schemas/MailboxCredential' mailbox: $ref: '#/components/schemas/Mailbox' warning: description: >- Optional warning string when the mailbox was created without an initial credential type: - string - 'null' required: - mailbox - credential - warning type: object ResponseMeta: additionalProperties: false properties: request_id: example: req_clxxxxxxxxxxxxxxxxxxxxxxxxx type: string required: - request_id type: object ApiErrorDetail: additionalProperties: false properties: code: description: >- Machine-readable issue code from the validator (e.g. zod issue code). example: invalid_string type: string field: description: Dot-path of the offending request field. example: recipient.email type: string message: description: Human-readable issue description. type: string required: - field - code - message type: object MailboxCredential: additionalProperties: false description: >- Initial credential for the mailbox. `null` if credential generation failed — call POST /mailboxes/{id}/keys to retry. properties: imap_port: description: IMAP retrieval port example: 993 type: integer key_prefix: type: string key_suffix: type: string public_id: description: Credential public ID example: smx_clxxxxxxxxxxxxxxxxxxxxxxxxx type: string secret: description: >- Mailbox credential — shown exactly once. Use as a Bearer token on the HTTP API and as the password for IMAP retrieval and SMTP submission. type: string server: description: Mailbox server name example: mail.sendmux.ai type: string smtp_port: description: SMTP submission port example: 587 type: integer username: description: Mailbox email address used as the login type: string required: - public_id - secret - key_prefix - key_suffix - server - imap_port - smtp_port - username type: - object - 'null' Mailbox: additionalProperties: false properties: created_at: description: ISO 8601 creation timestamp type: string display_name: description: Optional display name shown in outbound From headers type: - string - 'null' email: description: Mailbox email address (lowercase) example: agent@acme.com type: string id: description: Public ID example: mbx_clxxxxxxxxxxxxxxxxxxxxxxxxx type: string quota_bytes: description: >- Storage quota in bytes. Current writable tiers are 1 GB, 5 GB, and 50 GB. type: - integer - 'null' send_scope: $ref: '#/components/schemas/MailboxSendScope' status: description: active | suspended | deleted example: active type: string required: - id - email - display_name - quota_bytes - send_scope - status - created_at type: object MailboxSendScope: additionalProperties: false properties: group_public_ids: description: Delivery group public IDs (only when type=group) items: type: string type: array provider_public_ids: description: Provider public IDs (only when type=providers) items: type: string type: array type: description: >- 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. enum: - all - providers - group type: string required: - type type: - object - 'null' securitySchemes: bearerAuth: bearerFormat: API Key description: >- 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. scheme: bearer type: http ````