SMS Opt-outs

Ring2All Platform — SMS Opt-out Management

Parent Module: SMS Messaging

---

Overview

SMS Opt-outs manage phone numbers that have requested to stop receiving text messages. The system automatically handles STOP/START keywords and maintains a blocklist for compliance with messaging regulations.

Navigation

---

Configuration Fields

Automatic Keyword Handling

The system automatically processes these keywords from inbound messages:

Opt-Out Keywords (Block)

Opt-In Keywords (Unblock)

Help Keywords (No Action)

Automatic Response Messages

When keywords are detected, the system can send automatic responses:

STOP Response

"You have been unsubscribed and will not receive any more messages from this number. Reply START to resubscribe."

START Response

"You have been resubscribed to messages from this number. Reply STOP to unsubscribe."

HELP Response

"For help, visit [your website] or call [your phone number]. Reply STOP to unsubscribe."

💡 Tip: Response messages are configurable in SMS Settings.

---

Opt-out Behavior

When a message is sent to an opted-out number:

Outbound Message to +15551234567
           │
           ▼
┌─────────────────────┐
│ Check Opt-out List  │
└──────────┬──────────┘
           │
     Number found?
      Yes  │  No
      ─────┼─────
      │    └──▶ Continue sending
      │
      ▼
┌─────────────────────┐
│ Reject Message      │
│ Status: "rejected"  │
│ Error: "opt-out"    │
└─────────────────────┘

The message:

• Is NOT sent to the carrier
• Is logged with status rejected
• Error code indicates opt-out block

---

Manual Opt-out Management

Adding an Opt-out

1. Go to SMS → Opt-outs
2. Click + Add Opt-out
3. Enter phone number in E.164 format
4. Select reason (STOP, UNSUBSCRIBE, Manual, etc.)
5. Click Save

Removing an Opt-out

1. Find the opt-out in the list
2. Click Delete icon
3. Confirm removal

⚠️ Warning: Manually removing an opt-out should only be done with explicit consent from the recipient.

Bulk Import/Export

For managing large opt-out lists:

• Download current opt-out list as CSV

• Upload CSV with phone numbers
• Format: phone_number,reason

---

Compliance Requirements

TCPA (US)

The Telephone Consumer Protection Act requires:

CAN-SPAM

For commercial messages:

CASL (Canada)

Canadian Anti-Spam Legislation:

GDPR (EU)

For European recipients:

Opt-out List Best Practices

Do ✅

• Import existing opt-out lists when migrating
• Test opt-out with a test number before go-live
• Regularly audit opt-out list for data quality
• Keep records for at least 5 years
• Sync opt-outs across all messaging channels

Don't ❌

• Don't message opted-out numbers "just once"
• Don't require login to opt-out
• Don't charge for opt-out
• Don't share opt-out lists with third parties
• Don't remove opt-outs without explicit consent

---

Troubleshooting

Audit and Reporting

Opt-out Report Fields

Exporting for Compliance

To generate a compliance report:

1. Go to SMS → Opt-outs
2. Set date range filter
3. Click Export to CSV
4. Keep file for audit records

---

Database Schema

CREATE TABLE sms_optouts (
    id          SERIAL PRIMARY KEY,
    uuid        UUID DEFAULT gen_random_uuid(),
    domain_id   INTEGER NOT NULL,
    phone_number VARCHAR(20) NOT NULL,
    reason      VARCHAR(50) DEFAULT 'STOP',
    created_at  TIMESTAMP DEFAULT NOW(),
    created_by  INTEGER,
    UNIQUE(domain_id, phone_number)
);

CREATE INDEX idx_sms_optouts_phone ON sms_optouts(phone_number);
CREATE INDEX idx_sms_optouts_domain ON sms_optouts(domain_id);

---

API Reference

Check Opt-out Status

GET /api/sms/optouts/check?phone=+15551234567

Response:

{
  "opted_out": true,
  "reason": "STOP",
  "opted_out_at": "2026-01-15T10:30:00Z"
}

Add Opt-out

POST /api/sms/optouts
Content-Type: application/json

{
  "phone_number": "+15551234567",
  "reason": "Manual - customer request"
}

Remove Opt-out

DELETE /api/sms/optouts/{id}

---

Glossary

Lua Script Status ℹ️

Integration Module