> This page is part of the [Customer.io documentation](https://docs.customer.io). For the complete index, see [llms.txt](https://docs.customer.io/llms.txt).
> Last updated: September 14, 2026
> To take actions in Customer.io from an agent, use the [Customer.io CLI](https://docs.customer.io/ai/cli/get-started.md) or the [MCP server](https://docs.customer.io/ai/mcp/get-started.md).

# SMS: unsendable numbers

When a provider tells us that a phone number can't receive SMS, we stop sending SMS to that number so you don't pay to text phone numbers that can't receive your messages.

This feature only applies to Twilio SMS

While we plan to support other providers in the future, it only applies to Twilio SMS today. For bounces from other providers, Customer.io does not set the `cio_sms_unsendable_reason` attribute.

Some phone numbers can’t receive SMS: they’re invalid, they belong to a landline, or the handset can’t be reached. Every attempt to send to these numbers costs you money, drags down your sender reputation, and clutters your delivery metrics with bounces.

To prevent this, Customer.io watches for SMS bounces. When a provider tells us that a phone number can’t receive SMS, we flag the profile and stop sending SMS/MMS to that number. The way we handle bounced SMS messages is very similar to the way we handle SMS [opt outs](/messaging/channels/sms/keyword-opt-out/).

## How it works

When an SMS bounces with a provider error telling us that the number can’t receive SMS, we set a reserved [`cio_sms_unsendable_reason`](/messaging/profiles/manage/attributes/#reserved-attributes) attribute on the profile. The value records why the number can’t receive SMS:

Value

What it means

`invalid`

The number isn’t a valid phone number that can receive SMS.

`landline`

The number belongs to a landline, which can’t receive SMS.

`unreachable`

The carrier or handset can’t be reached for SMS.

The attribute also tells Customer.io to drop future SMS to that person’s `phone` number. We record these messages with the [`dropped` metric](/messaging/channels/sms/metrics/), the same metric we use when we skip messages for opted-out recipients. Dropped messages don’t count as bounces and don’t cost you a provider request.

### Dropped SMS messages don’t affect other message types

The `cio_sms_unsendable_reason` attribute is tied to the profile’s `phone` attribute and only applies to SMS messages. Customer.io will still send other kinds of messages to the user—email, push, in-app, etc.

WhatsApp bounces don’t set or rely on this attribute. WhatsApp bounces don’t include information about why they bounced, so we don’t apply or observe the `cio_sms_unsendable_reason` attribute for WhatsApp messages.

If you use a different attribute to represent the phone number, the `cio_sms_unsendable_reason` attribute doesn’t apply. For example, if you store a `preferred_phone` attribute and try to send to that rather than `phone`, any change to the `cio_sms_unsendable_reason` attribute won’t apply.

### Customer.io automatically clears `cio_sms_unsendable_reason` when a phone number changes

If you update a profile’s `phone` attribute, we’ll clear the `cio_sms_unsendable_reason` attribute so the new number can receive SMS messages. You don’t need to remove the `cio_sms_unsendable_reason` attribute yourself.

## Find and segment unsendable numbers

You can [segment](/messaging/segmentation/segments/) on the `cio_sms_unsendable_reason` attribute like any other attribute. This can help you find profiles that can’t receive SMS. You might do this either to exclude them from your automation workflows or to clean out inactive profiles. For example you might create a segments with the following conditions:

*   Segment where `cio_sms_unsendable_reason` **exists** to find every profile with a number that can’t receive SMS.
*   Segment where `cio_sms_unsendable_reason` **equals** `landline` to find profiles whose number is a landline, so you can reach them on another channel instead.

`cio_sms_unsendable_reason` is a [reserved attribute](/messaging/profiles/manage/attributes/#reserved-attributes) that Customer.io sets and clears for you. You can’t set or edit its value yourself.

©2026 Peaberry Software, Inc. [Status](https://status.customerio.com/) [Terms of Service](https://customer.io/legal/terms-of-service/) [Privacy Policy](https://customer.io/legal/privacy-policy/)

[](https://www.linkedin.com/company/customer-io)[](https://twitter.com/customerio)[](https://www.youtube.com/channel/UCkCaWdezRoa8ZyR9pEVaipA)[](https://www.instagram.com/customer.io/)