---
title: "Release the inbox phone number"
method: DELETE
path: "/api/v1/inboxes/{id}/phone-number"
tags: ["SMS"]
---

# Release the inbox phone number

`DELETE /api/v1/inboxes/{id}/phone-number`

## Request

- Base URL: `https://cooperemail.com`
- URL: `https://cooperemail.com/api/v1/inboxes/{id}/phone-number`
- Auth: HTTP bearer

Requires inbox_update. Releases the number at the provider and marks it released. With COOPER_SMS_BILLING=stripe, the subscription quantity is lowered and Stripe prorates the charge. A failure to update Stripe is retried by the next provision or release, which recompute the quantity from the database. The same account waits 30 days before provisioning that E.164 again. HTTP 404 phone_number_not_found when there is no active number. HTTP 404 not_found when SMS is off.

## Path parameters

- `id` string, required

## Response `200`

Released number. inbox_id is null.

- PhoneNumber
  - `object` 'phone_number', required
  - `id` string, required
  - `account_id` string, required
  - `inbox_id` string, nullable
  - `e164` string, required
  - `provider` string, required
  - `provider_sid` string, required
  - `number_type` string, required
  - `capabilities` string[], required
  - `status` 'pending' | 'active' | 'released', required
  - `outbound` string, required: disabled until a 10DLC brand is attached. enabled is required before POST /sms succeeds.
  - `brand_id` string, nullable
  - `created_at` string, date-time, required
  - `released_at` string, date-time, nullable
  - `voice_greeting` string, nullable: Spoken before a voicemail recording. Null uses the default greeting. Present when voice is on.
  - `voice_max_seconds` integer, nullable: Recording cap from 15 to 300. Null uses 120 seconds, or 60 once the minute allowance is used. Present when voice is on.
  - `billing` PhoneNumberBilling: Present on provision and on an idempotent replay. included is $0 (Pro's first 3 numbers, or an operator). billed means COOPER_SMS_BILLING=stripe put this number on the subscription. stub means billing is off and stripe_price_id is the env price id or null. Cooper does not charge from a stub.
    - `addon` 'cooper_phone_number_monthly', required
    - `status` 'included' | 'stub' | 'billed', required
    - `monthly_cents` integer, required
    - `segments_included` integer, required
    - `stripe_price_id` string, nullable, required

## Other responses

- `404`: not_found, phone_number_not_found, or inbox_not_found

---

[API](https://skmtc.dev/cooperemail/apis/cooper-email-api.md) · [All operations](https://skmtc.dev/cooperemail/apis/cooper-email-api/llms.txt) · [OpenAPI document](https://skmtc.dev/cooperemail/apis/cooper-email-api/revisions/6d800a7b3e33?raw)