Twilio Error 21610

What is Twilio Error 21610?

Error 21610, "Attempt to send to unsubscribed recipient," is returned by the Twilio Messaging API when you try to send an SMS to a number that has previously opted out of your sender. Twilio rejects the request with an HTTP 400 response and the message is not sent and not billed.

Twilio (and the underlying carriers) enforce opt-out at the From/To pair level: once a handset replies STOP to your Twilio number, that specific sender→recipient combination is added to a block list. The block is handled by Twilio's STOP filtering layer before your message reaches the carrier, which is why you cannot override it from your own code or by retrying.

What causes Twilio Error 21610?

• The recipient replied with an opt-out keyword. For long codes, Twilio's default opt-out keywords are STOP, STOPALL, UNSUBSCRIBE, CANCEL, END, QUIT, REVOKE, and OPTOUT (the last two added as defaults per an FCC ruling that took effect April 11, 2025, with Twilio completing the rollout by May 13, 2025). Any of these from the recipient blocks the From/To pair.
• A toll-free number opt-out. Toll-Free SMS has a carrier-level opt-out layer outside Twilio that cannot be removed or customized. When a user texts STOP to a toll-free sender, they are opted out and told to reply UNSTOP to resume.
• Number reassignment. The phone number may have been reassigned to a new person who previously opted out, so the historical block still applies.

Twilio's own error text for 21610 is rendered as "The message From/To pair violates a blacklist rule" — this is the same error, not a separate one; both phrasings mean the destination number is on Twilio's internal opt-out block list.

How do I fix Twilio Error 21610?

You cannot lift the opt-out yourself — only the recipient can reverse it. Steps:

1. Stop retrying that From/To pair. Retries return the same 21610; suppress the number in your own system so you don't keep generating failed sends.
2. Have the recipient resubscribe. They must text an opt-in keyword to your Twilio sender:
3. Long codes: START or YES.
4. Toll-Free: START or UNSTOP (toll-free only honors these two). When Twilio sees a valid opt-in keyword, it removes the block-list entry for that number.
5. Confirm and audit consent. Only message recipients who have given express consent, per CTIA guidelines and Twilio's messaging policy. This both reduces 21610s and keeps you compliant.
6. (Optional) Use Advanced Opt-Out. If you run a Messaging Service, Twilio's Advanced Opt-Out lets you customize opt-out/opt-in keywords and confirmation messages, including localized keywords.

Handling it in code

Treat 21610 as a permanent suppression, not a transient failure — branch on the code rather than blindly retrying:

from twilio.base.exceptions import TwilioRestException

try:
    client.messages.create(to=to_number, from_=from_number, body=text)
except TwilioRestException as e:
    if e.code == 21610:
        suppress_recipient(to_number)  # do not retry; recipient opted out
    else:
        raise

If you send through Courier, 21610 surfaces on the message's delivery status from the Twilio provider; use it to update the user's subscription/preferences rather than re-attempting delivery.