A good SMS notification preferences page lets each person pick channels and topics separately, records exactly what they agreed to, and updates the moment they reply STOP by text. If any of those three break, you end up texting someone who said no, or showing a toggle that lies.
This guide is for product teams and developers who add texting to a SaaS product. We'll cover the data model, the screen, consent capture, the STOP sync back to the UI, and the line between transactional and marketing texts. Compliance here is risk reduction, not a guarantee, and your own counsel should review the wording.
The model: user, channel, topic
The direct answer: store one preference row per user, per channel, per topic, and never a single "notifications on" flag. A single flag can't express "texts for security alerts, email for weekly reports."
A minimal shape:
| Field | Example | Why it exists |
|---|---|---|
| user_id | the account member | Preferences belong to a person, not a company |
| channel | sms, email, push | Each channel has its own rules |
| topic | security, billing, product updates, promotions | Lets people keep what they value |
| enabled | true or false | The current choice |
| updated_at and source | settings page, text reply, admin | Tells you who changed it and how |
Add a phone number field per user and treat it as E.164 (like +12125550199). If you let one person change a number, mark SMS as unconfirmed until they confirm the new one. Numbers get reassigned, and our post on reassigned numbers and the TCPA explains why confirming matters.
Transactional versus marketing
The direct answer: separate the two on the screen and in your data, because the consent you need and the way people expect to opt out differ.
Transactional texts are the ones a person asked for or needs to run their account: a login code, a payment failure, a shipment update. Marketing texts promote something. The line isn't always obvious, and a message that mixes a receipt with a coupon is likely to be treated as marketing. When in doubt, classify as marketing and ask for the stronger consent.
On the page, group toggles under headings the user would use themselves:
- Account and security (login codes, suspicious activity)
- Billing (failed payments, receipts)
- Activity in your workspace (assignments, mentions, replies)
- Product news and offers (the marketing group, off until they opt in)
Default marketing to off. Default security to on only if the user gave their number for that purpose and was told so. If you handle one-time passcodes, keep that traffic apart from marketing numbers; use a separate number from your marketing texts.
Capturing and recording consent
The direct answer: show the exact wording next to the control, store that wording and the time, and keep the record in your own system.
Ready records the sender's attestation on a bulk send or an API send that sets consent_attested, but that's the sender's statement, not a per-contact consent record. No recipient opt-in time, wording or page URL is stored on Ready's side, so the record is yours to keep. (The one exception is a sign-up on a Ready-hosted opt-in page, which stores the time, IP and exact wording per contact.)
A useful consent record holds:
- The user and the phone number as agreed
- The exact disclosure text shown, with a version id
- The timestamp and the surface (settings page, onboarding, checkout)
- The topics covered
- Later changes, as new rows rather than overwrites
Our consent record schema for developers goes through a full table. For the disclosure itself, say who is texting, what kinds of messages, that message and data rates may apply, how often if you know, and how to stop ("Reply STOP to opt out"). Keep it next to the toggle, not buried in a link.
When you send through the API, pass consent_attested as true only when your record backs it up:
POST /v1/messages
{"to": "+12125550199", "body": "Your invoice payment failed. Update your card in Settings.", "consent_attested": true} Send an Idempotency-Key header with each request so a retry never sends twice. The messages API docs have the rest.
STOP sync back to the UI
The direct answer: a STOP reply must switch the SMS toggles off in your settings page, and it should happen without the user touching the page.
Ready honors inbound STOP and UNSUBSCRIBE automatically and catches clear phrases like "please stop texting me." The opt-out blocks that number in the sub-account that received it, and sends to an opted-out number are refused up front and not charged. That protects you at send time. It doesn't, by itself, update your own preferences table, so you have to sync.
Here's the pattern:
- Receive the opt-out through a webhook, or read
GET /v1/opt-outson a schedule. That list holds only this account's opted-out contacts, so a STOP held on another account of the same family or from a deleted contact isn't in it. CheckGET /v1/opt-outs/:phonefor a single number before sending from another tool, and see the opt-outs docs. - Map the phone number back to the user, then set every SMS preference for that user to disabled with source "text reply."
- Show the state on the page: "Texts are off because you replied STOP on March 3. Reply START to turn them back on." Keep the date as real data, not a hard-coded example.
- Don't let a toggle switch an opted-out number back on from the UI alone. A person who replied STOP should re-enable by texting START, or through a fresh confirmation step you can prove.
For the multi-channel version of this problem, see opt-out sync across channels.
The screen itself
The direct answer: keep it to a grid, one row per topic and one column per channel, with a phone number block above it.
Design notes that save support tickets:
- Show the number being used, masked to the last four digits, with a Change link.
- Show a clear state for each channel: on, off, or "needs confirmation."
- Use plain topic names, not internal event names.
- Autosave each toggle and confirm it with a short message, or use one Save button. Don't mix the two.
- Give admins a separate view of org-wide defaults so a workspace owner can't silently enable marketing for members.
- Add a one-line explanation under the SMS column: "Standard message rates may apply. Reply STOP to any text to stop them."
A test worth running: have someone unfamiliar with the product try to turn off all texts in under 15 seconds. If they can't, simplify.
Rules that reduce risk
The direct answer: respect quiet hours, keep audit history, and treat STOP as final until the person says otherwise.
Ready enforces quiet hours based on the recipient's area. Campaigns, drip campaigns and automations wait up to 24 hours for the window. An API text is held only if the window opens within a few hours; otherwise it isn't sent, and you send it again once the window opens. A text sent in reply to someone who texted you in the last 24 hours can go out at any hour. Build your notification code to handle that refusal instead of assuming every send goes through.
Also: don't put sensitive health details in texts. Ready isn't HIPAA compliant and doesn't sign BAAs, so a reminder should say "Your results are ready, please log in" rather than naming a diagnosis.
Frequently asked questions
Do I need separate consent for each topic?
Ask for consent that matches what you'll send. If a person agrees to security alerts, that doesn't cover promotions. Keep marketing as its own opt-in, off by default, and store the topics covered with each consent record.
Does Ready store my users' SMS consent?
No. Ready records the sender's attestation on bulk and API sends that set consent_attested, but not a per-contact opt-in time or wording. Keep your own consent records in your product or CRM.
What happens when someone replies STOP?
Ready honors it and blocks further texts to that number from the sub-account that received it. Your job is to sync that state into your preferences page so the toggles match reality.
Next step
Sketch the preference grid for your own product, list the texts you send today, and mark each as transactional or marketing. Then wire the STOP sync before you ship the UI, since it's the part users notice first. When you want to test the sending side, sign up and send a few one-to-one texts.