What is a STOP keyword, and what must happen when someone sends it?

A recipient can ask to stop after receiving a message from any of your numbers. Your application needs to connect that request to the messages it will send next.

What does Bird do with a recognized STOP?

Bird records an opt-out for the sender-and-subscriber pair. It then sends the configured confirmation.

It first matches the inbound text against the applicable keyword rules. The opt-out must be recorded before Bird confirms it, so a failed write cannot produce a misleading confirmation.

A later send from that sender to that subscriber returns E12077 SMSRecipientSuppressed. Bird refuses the request before creating an outbound message or delivery attempt. There is no delivery-failure event for that refused send.

By default, start ends the suppression. It then confirms the change. help and info return program information without changing the opt-out. Where no separate info rule exists, INFO can be a help keyword.

Does the opt-out cover every number I use?

The keyword suppression covers one sender and one subscriber, rather than every sender in your workspace.

For example, an opt-out from your marketing number does not automatically suppress a separate delivery-notification number. Your application must apply the scope of the person's actual request before using another sender.

For an all-sender opt-out, use a workspace-wide preference. That record is separate from an SMS suppression. It does not emit sms_suppression.created. An event handler watching only that event will miss preference changes.

The opt-out guide explains workspace-wide preferences. A keyword suppression rejects with E12077. A workspace-wide preference can reject with E25000 PreferenceRevoked.

How do I check whether Bird handles the keyword?

You list the rules that apply to the country or sending number before relying on automatic handling.

bird sms keyword-rules list --country NL

An empty country result means no rules were returned for that country. The command reference documents its filters, including --from-country.

Through the API, use GET /v1/sms/keyword-rules. Filter by number to inspect a specific number's rules. Results arrive most specific first, with the keywords that apply in effective_keywords.

Bird's built-in catalog covers only some countries. Without an applicable rule, the message reaches your inbound handler as ordinary text. Bird records no automatic opt-out or confirmation in that case. Your handler must recognize the request and stop subsequent sends.

Why can an opt-out confirmation still be sent?

Bird exempts built-in compliance replies from the suppression they need to acknowledge.

Without that exemption, recording a STOP would block its own confirmation. The exemption covers opt-out, opt-in, help and info replies. Other send checks still apply.

A custom keyword reply has no such exemption. Otherwise a custom response could deliver your chosen text to someone who has opted out.

The confirm operation marks a double opt-in reply. It sends no response. Your handler must answer it. A custom rule without reply text also sends nothing.

What should my application do after an opt-out?

Prevent future sends that conflict with the person's request. Record the opt-out's scope to apply it correctly.

Treat E12077 as a blocked send to investigate in your consent state, not a transient delivery failure to retry. Keep handlers for old sender numbers active while recipients can still reply to their messages.

Honor opt-outs received outside the built-in catalog or through other supported contact methods. The CTIA messaging principles expect senders to support and honor opt-out requests.

For programs using several numbers, check both sender-specific suppressions and workspace-wide preferences. That prevents a change of sender from bypassing the person's request.