Managing Opt-ins and Opt-outs

Understand how TextGrid processes subscription keywords, blocks messages to opted-out recipients, and exposes APIs for recording and checking messaging preferences.

Automatic keyword handling

With standard keyword handling enabled, TextGrid recognizes these complete incoming message values:

Matching ignores letter case and surrounding whitespace. For example, stop matches; a longer sentence containing the word STOP does not match this keyword check.

An opt-out records a blocked preference. A resubscription records an opted-in preference. HELP does not itself change the subscription preference.

Support can help disable standard keyword handling, control whether confirmations are sent, and customize confirmation and help text. Custom account responses can also affect preference handling. Confirm your account configuration before implementing additional replies.

Receive keyword messages in your application

Keyword processing happens before the normal incoming-message callback. When incoming callbacks are enabled and configured, keyword messages can still be forwarded to your smsUrl with the usual message fields.

Verify the callback signature, record the recipient's preference in your application, and return an acknowledgment without a generic reply. Do not assume a keyword message was withheld from your webhook simply because TextGrid handled it.

When TextGrid has already sent an automatic response, it skips processing the callback's reply TwiML. This does not prevent your application from independently submitting another outgoing API message, so your own workflows must avoid duplicate or inappropriate replies.

See Receiving SMS and MMS for callback processing and Verifying Webhook Signatures for signature verification.

Understand suppression scope

The outgoing-message path checks opt-out and blacklist rules before sending. A blocked request can be rejected with a blacklist-related error.

Do not assume every opt-out is limited to one sending number. Depending on account configuration, keyword preferences can be recorded at sending-number or account/agency scope, and additional blocking rules can apply. Switching sending numbers is not a reliable way to determine or change a recipient's eligibility.

Keep your application's messaging preferences in sync and stop queued or scheduled messages when an opt-out is received. Record an opt-in only when the recipient has actually requested or authorized it; updating an API preference is not evidence of that authorization.

Manage preferences through the API

Use the preference APIs when a recipient requests a change through your application rather than by sending a keyword—for example, through an account settings page or a conversation with your support team.

You can update one recipient or a group of recipients, and retrieve the latest recorded preference for a sending-number/recipient pair. Choose whether to request confirmation messages when using the group update operation. Confirmation behavior also depends on account settings.

Record changes made by your application: API preference updates do not generate a separate incoming-message webhook. If an update fails, check the recorded preferences before retrying, since some changes may already have been applied.

A preference lookup does not check every rule that can block sending. Broader account or agency restrictions may still apply, and the absence of an opt-out record does not establish consent.

See the Opt User In/Out, Opt recipients in or out, and Get recipient opt-in status endpoints in the API Reference for request fields, notification options, and response details.

Test your integration

Using numbers you control, test a STOP message, a repeated STOP, a START, and HELP. Confirm that your application records the messages, does not send duplicate confirmations, and stops future sends when the recipient opts out.

Also test the API preference operations with notifications disabled before enabling confirmation messages. Account-specific behavior should be verified against your configured keyword and response settings.