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

A STOP keyword is the word a subscriber texts back to make you stop. The question worth answering is not what the word is but what it actually changes, because on Bird the answer is narrower than most people assume in one direction and entirely absent in another.

What does Bird do when someone texts STOP?

Three things, in order, and then a fourth thing forever after.

1. Recognises it, by matching the inbound text against the keyword catalog for that number's country.
2. Records a suppression on that exact sender-and-subscriber pair.
3. Replies, with the opt-out confirmation for that country.

From then on, a send from that sender to that subscriber is refused with E12077 rather than being sent and failing. That distinction matters when you go looking for evidence: there is no message, no delivery attempt and no failure event, because the send never happened.

Three sibling operations complete the set. A START ends the suppression and confirms that too. A HELP replies with your program information and changes nothing, and INFO does the same: it is a separate operation so that a country whose INFO answer must differ from its HELP answer can carry both, and where no INFO rule ships for a country, INFO is simply one of that country's help keywords.

Does a STOP stop everything I send?

No, and this is the part that surprises people. A suppression covers one sender and one subscriber.

It is not workspace-wide. Someone who opts out of one of your numbers still hears from your others. That is a deliberate design rather than an oversight: it lets a person stop your marketing while continuing to get delivery notifications from the number that sends them.

The consequence is that "did this person opt out?" is not a question with a single answer. It is a question per sender. If your intent is that a STOP to any of your numbers stops all of them, you have to implement that yourself, by watching for the suppression and applying it across your other senders.

There is a separate, broader mechanism for stopping every sender in a workspace at once, and it behaves differently in a way worth knowing if you mirror suppressions: a workspace-wide opt-out recorded that way is a stated preference rather than a suppression, and it does not fire sms_suppression.created. Code that mirrors only that event will miss those.

What happens in a country Bird does not cover?

Nothing, and this is the answer to the "must" in the question.

Bird's keyword catalog covers a subset of countries. Where a country is covered, opt-out, opt-in and help keywords are handled by default. Where it is not, Bird recognises no keyword, sends no reply, and records no opt-out. The inbound message arrives as an ordinary inbound message and nothing else happens.

So if you send to a country outside the catalog, nothing on Bird's side will recognise an opt-out or act on one. Detecting it in your inbound handler and recording the suppression yourself is the only thing that will stop the next send.

Check before you rely on it rather than after:

bird sms keyword-rules list --country NL

An empty result means that country has no coverage, and the command reference carries the flags in full, including the --from-country one for checking what a sender messaging from elsewhere gets. GET /v1/sms/keyword-rules answers the same question over the API, and asking it for one of your numbers returns the rules in the order they are applied to an inbound message, most specific first, each carrying the keywords in force for it.

Why can Bird reply to someone it just suppressed?

Because the confirmation is exempt from the suppression it creates, and the exemption is deliberately narrow.

Without it the system would contradict itself: the suppression recorded a moment ago would block the message telling the subscriber it worked. So the regulated replies, the opt-out, opt-in, help and info answers, are allowed through.

What is not exempt is a keyword you invented. A custom rule's keywords and reply text are yours, so treating one as a regulated answer would let a message of your choosing reach someone who has opted out, as long as they happened to text a word you had claimed. Custom replies are therefore subject to the suppression like anything else.

One operation in the catalog is worth knowing about before you rely on it. confirm marks a double opt-in reply such as a JOIN or a YES, and it sends nothing today. Bird holds those keywords so that a custom rule cannot claim them, but answering them is your handler's job. A custom rule with no reply text configured likewise sends nothing.

What should I actually build?

Four things, given the above.

1. Mirror suppressions across your senders if your policy is that a stop means stop. Bird will not do it for you, and sms_suppression.created is the event to watch.
2. Handle opt-outs yourself outside the catalog, and know which of your destination countries are covered before you send rather than after a complaint.
3. Treat E12077 as expected, not as an error. It means the system did its job. Log it, do not alert on it, and do not retry it.
4. Answer your own confirm keywords if you run a double opt-in, since nothing replies to them for you.

Opt-outs and keywords covers the catalog, how to see what applies to a given number, and how to replace a default reply with your own. For the wider industry guidance that sits behind opt-out expectations in the United States, CTIA publishes its Messaging Principles and Best Practices.