Compliance: Managing Opt-Outs (STOP, QUIT)
Opt-outs are a standard part of SMS compliance: contacts must be able to stop messages at any time.
If you use Twilio with RapidPro.app, Twilio automatically handles opt-out and opt-in keywords, and RapidPro.app reflects those opt-outs
so you don’t accidentally keep messaging someone who has stopped.
Quick setup checklist
Use this checklist to confirm your opt-out handling is correct from end to end.
- Confirm which opt-out keywords Twilio enforces (STOP, QUIT, etc.).
- Verify how RapidPro.app reflects Twilio opt-outs (Stopped group + outbound blocking).
- Learn how contacts opt back in (START) and how to troubleshoot delivery failures.
- Enable monitoring for Twilio blacklist errors (e.g., 21610) and keep clean reporting.
- Review common issues and fixes.
When a contact sends an opt-out keyword to your Twilio number, Twilio blocks further outbound SMS to that contact
until they opt back in.
Twilio treats the following inbound keywords as opt-out requests:
- STOP
- STOPALL
- UNSUBSCRIBE
- CANCEL
- END
- QUIT
- Twilio blocks additional messages to that contact until they send START.
- Twilio may also send standard confirmation messages (opt-out confirmation, and opt-in confirmation after START).
Twilio enforces the block at the provider level—even if your flow tries to send, Twilio won’t deliver until the contact opts back in.
[CAPTURE: Example conversation showing STOP sent to the Twilio number and Twilio’s opt-out confirmation reply.]
When Twilio notifies RapidPro.app that a contact is blacklisted (opted out) for one of your Twilio numbers,
RapidPro.app updates the contact state so you don’t accidentally continue messaging them.
- The contact is placed into the default Stopped group (in Contacts).
- The contact is removed from all other groups.
- Outbound message attempts are blocked to prevent accidental sending to an opted-out contact.
[CAPTURE: Contact profile showing the contact in the default “Stopped” group.]
If messages aren’t delivering and you suspect an opt-out, validate it at the provider level first, then confirm the contact state in RapidPro.app.
The contact must send START to your Twilio number. Twilio controls re-subscribe behavior.
Once they opt back in, re-test sending from a simple flow.
- Open message logs for the failed message attempt and look for Twilio error codes.
- Check the contact’s group status (Stopped) and recent inbound keywords (STOP/QUIT, etc.).
[CAPTURE: Message log showing a Twilio error code for blacklist/opt-out.]
Opt-outs are normal. What matters is detecting them quickly, preventing accidental sending, and keeping reporting meaningful.
Enable Twilio error notifications and watch for opt-out related errors such as 21610 (blacklist / opted out).
This helps confirm that a delivery failure is compliance-related (not a flow logic issue).
- Always include clear opt-out guidance in your program messaging where required by your region.
- Use flows and groups to segment “stopped” or “do-not-contact” contacts for reporting and follow-up.
- When investigating a complaint, check both inbound keywords and provider logs before changing flow logic.
[CAPTURE: Twilio dashboard or logs showing an error/notification for 21610.]
Common issues
My flow says it sent, but the contact didn’t receive anything
Check whether the contact opted out using STOP/QUIT (Twilio will block delivery). Then review message logs for Twilio error codes
(commonly 21610 for blacklist/opted out).
How do I resume messaging a stopped contact?
The contact must send START to your Twilio number (Twilio controls re-subscribe). After that, re-test sending and confirm
the contact is no longer treated as opted out in RapidPro.app.
The contact is in “Stopped” but claims they didn’t opt out
Review inbound messages for STOP-style keywords and cross-check Twilio logs/error codes for blacklist events.
If needed, confirm which number/channel the opt-out happened on.
I keep seeing error 21610 in logs
This typically indicates the destination is opted out/blacklisted at Twilio. Confirm the contact opted out and advise them to text START
if they want to re-subscribe. Avoid repeated send attempts until they opt back in.