Every recipient can text STOP to opt out, HELP to get a help response, and START to opt back in. Bird honors these keywords automatically on every send and keeps a per-recipient suppression list you can query — no extra code on your side.
import { BirdClient } from "@messagebird/sdk";
const bird = new BirdClient({ apiKey: process.env.BIRD_API_KEY! });
const code = generateOtp();
const { data, error } = await bird.sms.send({
from: "Bird",
to: "+15005550006",
text: `Your Bird verification code is ${code}. Reply STOP to opt out.`,
}).safe();
if (error) throw error;
console.log(data.id);
// → "sms_4kT01Lq2m..."Today at 2:14 PM
Opt-out is the one rule that's always on.
Opt-out handling is part of SMS compliance on the Bird SMS API, and unlike registration it applies everywhere you send, with no setup. The reserved keywords STOP, HELP, and START are recognized in inbound messages and acted on per recipient, so a person who opts out stays opted out across your sends until they choose to come back.
How the keywords behave.
Reserved keywords, enforced per recipient.
- 01
STOP suppresses automatically.
When a recipient texts STOP, Bird adds them to the suppression list and blocks further sends to that number without any action from you.
- 02
HELP returns a help response.
A recipient who texts HELP gets an automatic help reply, so you meet the carriers' help-keyword requirement without wiring a handler.
- 03
START resubscribes them.
Opt-out is reversible. A recipient who texts START is removed from suppression and can receive messages again — they're always in control.
- 04
The suppression list is queryable, per recipient.
Check whether a number is suppressed through the API before you build an audience, so an opted-out recipient never slips back into a send.
An opt-out arrives as a signed event.
When a recipient opts out, Bird suppresses them and notifies your webhook with an sms.opted_out event so your own records stay in sync. The event is HMAC-signed like every Bird webhook.
{
"type": "sms.opted_out",
"data": {
"from": "+15005550006",
"keyword": "STOP",
"suppressed": true
}
}Opt-out is an inbound flow.
STOP, HELP, and START arrive the same way any reply does — as inbound messages on two-way numbers. Bird intercepts the reserved keywords and acts on them before they reach your application logic, so you get the suppression behavior for free and still see everything else your recipients send.
Opt-out FAQ
Do I have to handle STOP myself?+
What do STOP, HELP, and START each do?+
Can a recipient who opted out come back?+
How do I check if a number is suppressed?+
Other compliance topics
Opt-out is one of three SMS compliance regimes. See the rest.
Honor every opt-out without writing a handler.
Opt-out is one regime of SMS compliance on Bird. STOP, HELP, and START are enforced on every send, with a suppression list you can query from the same API.