---
title: "Claim or rent a mailbox"
method: POST
path: "/mailboxes"
tags: ["Mailboxes"]
---

# Claim or rent a mailbox

`POST /mailboxes`

## Request

- Base URL: `https://api.mobilerun.ai`
- URL: `https://api.mobilerun.ai/mailboxes`
- Auth: HTTP bearer

Creates a mailbox on the default domain or a connected custom domain. An optional `localPart` selects the address. Replaying the same Idempotency-Key and payload returns the original mailbox. Fresh requests and replays return 202 with the current mailbox state. Poll the mailbox when the response does not yet include a checkout URL.

## Headers

- `idempotency-key` string: Idempotency-Key: 1-255 printable ASCII characters. Same key with a different request body is a 422 idempotency_key_reused. A retryable in-flight duplicate is a 409 with Retry-After and x-should-retry: true; a terminal duplicate is a 409 with x-should-retry: false. A replay returns the current resource state with Idempotent-Replayed: true.

## Request body

- CreateMailboxRequest
  - `label` string
  - `domainId` string, uuid: Optional active custom mailbox domain owned by the caller. Omit to use the system domain.
  - `localPart` string: Optional mailbox name before the "@". Omit to generate a random address.
  - `billingPreference` 'included' | 'included_only' | 'rent': included uses package capacity when available and otherwise starts paid checkout; included_only fails without creating a paid reservation when no included slot remains; rent always starts paid checkout.

## Response `200`

Archived mailbox returned (idempotent replay)

- object
  - `data` Mailbox, required
    - `id` string, uuid, required
    - `provider` 'matix' | 'gmail', required
    - `domainId` string, uuid, nullable, required
    - `address` string, nullable, required
    - `label` string, nullable, required
    - `status` 'provisioning' | 'awaiting_payment' | 'active' | 'cancel_scheduled' | 'archived' | 'billing_error' | 'pending_connection' | 'connection_expired' | 'connection_removed', required
    - `billingMode` 'rent' | 'included' | 'domain' | 'external', required
    - `cancelAtPeriodEnd` boolean, required
    - `checkoutUrl` string, nullable, required
    - `checkoutExpiresAt` string, date-time, nullable, required
    - `currentPeriodEnd` string, date-time, nullable, required
    - `createdAt` string, date-time, required
    - `inboundMessages` MailboxInboundMessagesUsage, required
      - `used` integer, required
      - `included` integer, required
      - `exhausted` boolean, required
      - `resetsAt` string, date-time, nullable, required

## Other responses

- `201`: Fresh creates and replays return 202; clients must treat any 2xx response as success
- `202`: Mailbox creation accepted; poll the mailbox for updates
- `400`: The mailbox backend rejected the request, or the Idempotency-Key header is malformed
- `401`: Unauthorized
- `409`: Address taken or included capacity unavailable
- `422`: Invalid, reserved, or disabled custom local part, or the Idempotency-Key was reused with a different request
- `429`: A rental cap was reached, or the mailbox backend rate limited the request
- `500`: Internal Server Error
- `502`: Mailbox backend unavailable
- `503`: Mailboxes disabled or billing not configured

## Changes

- **2026-10-21** `559a12449213`: 20 warning
  - added the new `integration_forbidden` enum value to the `anyOf[#/components/schemas/MailboxApiErrorEnvelope]/code` response property for the response status `400`
  - added the new `integration_forbidden` enum value to the `anyOf[#/components/schemas/MailboxApiErrorEnvelope]/code` response property for the response status `422`
  - added the new `integration_forbidden` enum value to the `anyOf[#/components/schemas/MailboxApiErrorEnvelope]/code` response property for the response status `429`
  - added the new `integration_forbidden` enum value to the `anyOf[#/components/schemas/MailboxApiErrorEnvelope]/code` response property for the response status `502`
  - …16 more
- **2026-10-16** `4ad548c528a8`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/droidrun/apis/droidrun-cloud/changes/mailboxes/post.md)

---

[API](https://skmtc.dev/droidrun/apis/droidrun-cloud.md) - [All operations](https://skmtc.dev/droidrun/apis/droidrun-cloud/llms.txt) - [OpenAPI document](https://skmtc.dev/droidrun/apis/droidrun-cloud/revisions/1cc95586c933?raw)