---
title: "Add an SMS inbox for a number on the company's own Twilio account. Banger checks the account owns the number, points its incoming texts at the inbox, and keeps the Auth Token encrypted. A workspace admin signed in to the web app does this; it needs the customers workspace feature."
method: POST
path: "/v1/workspaces/{workspaceId}/mailboxes/sms"
---

# Add an SMS inbox for a number on the company's own Twilio account. Banger checks the account owns the number, points its incoming texts at the inbox, and keeps the Auth Token encrypted. A workspace admin signed in to the web app does this; it needs the customers workspace feature.

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

## Request

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

## Request body

- object
  - `account_sid` string, required
  - `auth_token` string, required
  - `phone_number` string, required: The Twilio number in E.164.
  - `display_name` string

## Response `201`

The SMS inbox.

- 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

- `400`: Twilio refused the credentials
- `403`: The authenticated actor cannot perform this operation directly.
- `409`: The number is already an inbox in this workspace.
- `502`: Twilio didn't answer or didn't let Banger route the number.

---

[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)