---
title: "Create a hosted mailbox restricted to same-product hosted inboxes and the workspace signup recipient."
method: POST
path: "/v1/workspaces/{workspaceId}/mailboxes/starter"
---

# Create a hosted mailbox restricted to same-product hosted inboxes and the workspace signup recipient.

`POST /v1/workspaces/{workspaceId}/mailboxes/starter`

## Request

- Base URL: `https://api.bangermail.com`
- URL: `https://api.bangermail.com/v1/workspaces/{workspaceId}/mailboxes/starter`
- Auth: HTTP bearer

## Headers

- `Idempotency-Key` string, required

## Request body

- object
  - `create_new` boolean: Create an additional hosted mailbox instead of resuming the initial one.
  - `local_part` string: Name before @bangermail.com. Without it the mailbox gets a word name such as quiet-maple-harbor.
  - `display_name` string

## Response `200`

Idempotent replay of starter identity creation.

- object
  - `data` Mailbox, required
    - `id` string, uuid, required
    - `workspace_id` string, uuid, required
    - `product_id` string, uuid, nullable: The product (project) the mailbox belongs to. Clients group mailboxes and build web-app links with it.
    - `domain_id` string, uuid, nullable
    - `address` string, required: The email address, or for an SMS inbox its phone number in E.164 (+15551234567).
    - `display_name` string, required
    - `provider` 'gmail' | 'smtp' | 'twilio', required
    - `channel` 'email' | 'sms' | 'whatsapp': email; sms for an SMS inbox on Twilio; whatsapp for a WhatsApp inbox, a WhatsApp sender on Twilio for the business's WhatsApp Business account.
    - `sms_verification` object, nullable: A number from Banger, carriers' answer on its toll-free verification. It sends once approved; null for every other mailbox.
      - `status` 'pending_review' | 'in_review' | 'approved' | 'rejected'
      - `reason` string, nullable: Carriers' reason when rejected.
    - `status` 'pending' | 'active' | 'suspended' | 'reconnect_required' | 'disabled', required
    - `status_reason` string, nullable
    - `suspended_at` string, nullable
    - `mailbox_kind` 'domain' | 'starter', required

## Other responses

- `201`: Starter Banger address created.

---

[API](https://skmtc.dev/bangermail/apis/banger-api.md) · [All operations](https://skmtc.dev/bangermail/apis/banger-api/llms.txt) · [OpenAPI document](https://skmtc.dev/bangermail/apis/banger-api/revisions/a149909267f9?raw)