> ## Documentation Index > Fetch the complete documentation index at: https://docs.mermail.app/llms.txt > Use this file to discover all available pages before exploring further. # Create mailbox > **Plans:** `Free` · `Developer` · `Enterprise` Provisions a mailbox. `workspaceId` is required in the body for this route (or is supplied by the API key’s bound workspace). Requires workspace **admin**. Returns **201**. Costs **provision** credits (10). **API credits:** 10 (provision). ## OpenAPI ````yaml /openapi/openapi.json post /api/v1/mailboxes openapi: 3.1.0 info: title: Mermail API version: 1.0.0 description: > Programmatic Mermail API for scripts, agents, and integrations. ## Authentication Authorize with an API key from **Settings → API Keys**: ``` x-api-key: sk-proj-… ``` ## Plans Each endpoint page shows plan badges (**Public**, **All plans**, or **Developer+**). Free can call the core catalog; Developer-gated paths need Developer or Enterprise. ## Try it Every endpoint page includes an interactive playground. Click **Try it**, paste your API key into the `x-api-key` field, fill path/query/body fields (prefilled from examples), and send a live request to `https://console.mermail.app`. You can also copy the generated cURL / JavaScript / Python snippet. ## Credits | Class | Cost | | --- | ---: | | read | 1 | | write | 2 | | email_send | 5 | | provision | 10 | | ai_light | 15 | | ai_heavy | 25 | contact: name: Mermail email: contact@mermail.app url: https://mermail.app servers: - url: https://console.mermail.app description: Production security: - apiKeyAuth: [] tags: - name: Public description: No authentication - name: Usage description: Credits and email quotas - name: Workspaces description: Workspaces, members, storage - name: Domains description: Custom email domains (Developer+) - name: Mailboxes description: Agent inboxes - name: Emails description: Send, list, search, folders - name: AI agent description: Mailbox agent chat - name: Task triage description: Task triagers (all plans) - name: RAG description: Knowledge documents and recall - name: Integrations description: Composio, Telegram, push - name: Affiliate description: Affiliate program paths: /api/v1/mailboxes: post: tags: - Mailboxes summary: Create mailbox description: >- **Plans:** `Free` · `Developer` · `Enterprise` Provisions a mailbox. `workspaceId` is required in the body for this route (or is supplied by the API key’s bound workspace). Requires workspace **admin**. Returns **201**. Costs **provision** credits (10). **API credits:** 10 (provision). parameters: [] requestBody: required: true content: application/json: schema: type: object required: - email - name - workspaceId properties: email: type: string format: email description: Mailbox address on an allowed Mermail or custom domain example: support@mail.acme.com name: type: string description: Display name (also seeds settings.fromName) example: Acme Support workspaceId: type: string description: Required for `POST /api/v1/mailboxes` example: ws_01abc settings: type: object additionalProperties: true description: Optional mailbox settings merged over defaults example: email: ops@mail.acme.com name: Acme Ops workspaceId: ws_01abc responses: '201': description: Mailbox created content: application/json: schema: $ref: '#/components/schemas/Mailbox' example: id: support@mail.acme.com public_id: aaaaaaaa-bbbb-4ccc-8ddd-eeeeeeeeeeee workspace_id: ws_01abc email: ops@mail.acme.com name: Acme Ops email_domain_id: ed_01xyz inbound_provider: cloudflare_routing outbound_provider: cloudflare_email provider_metadata: domain: mail.acme.com provider: resend bucket_id: bkt_01xyz settings: forwarding: enabled: false email: '' signature: enabled: false text: '' autoReply: enabled: false subject: '' message: '' agentAutoResponse: requireApproval: true fromName: Acme Support welcome_onboarding_status: pending '400': description: Missing workspaceId or validation error content: application/json: schema: $ref: '#/components/schemas/Error' example: error: workspaceId is required '401': description: Missing, invalid, expired, or revoked API key / token content: application/json: schema: $ref: '#/components/schemas/Error' example: error: Unauthorized '402': description: API credits exhausted for this workspace period content: application/json: schema: $ref: '#/components/schemas/Error' example: error: Invalid request '403': description: Forbidden — plan gate, wrong workspace, or missing role content: application/json: schema: $ref: '#/components/schemas/Error' example: error: Forbidden '429': description: Rate limit exceeded (workspace RPM or email send limits) content: application/json: schema: $ref: '#/components/schemas/Error' example: error: Too many requests headers: Retry-After: schema: type: integer description: Seconds until the rate limit window resets security: - apiKeyAuth: [] components: schemas: Mailbox: type: object properties: id: type: string description: Hosted alias primary key (also accepted as mailboxId) public_id: type: string format: uuid description: Stable public route id; preferred mailboxId for agents and clients workspace_id: type: string email: type: string format: email name: type: string email_domain_id: type: string nullable: true inbound_provider: type: string outbound_provider: type: string provider_metadata: type: object additionalProperties: true bucket_id: type: string nullable: true settings: type: object additionalProperties: true welcome_onboarding_status: type: string inbox_unread_by_category: type: object description: Present on list endpoints only properties: customer_support: type: integer partnership: type: integer technical: type: integer other: type: integer Error: type: object required: - error properties: error: type: string example: Unauthorized code: type: string securitySchemes: apiKeyAuth: type: apiKey in: header name: x-api-key description: >- API key (`sk-proj-…`) from Settings → API Keys. Required for sold API calls outside the Mermail console. ````