SMS Marketing Compliance Guide for Developers

CREATE TABLE sms_consent (
  id            SERIAL PRIMARY KEY,
  phone_number  VARCHAR(20) NOT NULL,      -- E.164 format: +15125551234
  consent_given BOOLEAN DEFAULT FALSE,
  consent_type  VARCHAR(50),               -- 'marketing', 'transactional', 'both'
  consent_source VARCHAR(100),             -- 'web_form', 'sms_keyword', 'paper'
  consent_text  TEXT,                       -- Exact disclosure text shown at opt-in
  consented_at  TIMESTAMP,
  opted_out     BOOLEAN DEFAULT FALSE,
  opted_out_at  TIMESTAMP,
  ip_address    VARCHAR(45),               -- For web form opt-ins
  created_at    TIMESTAMP DEFAULT NOW()
);

-- Index for fast lookups before sending
CREATE INDEX idx_consent_phone ON sms_consent(phone_number, opted_out);

import re
from datetime import datetime

def normalize_phone(phone: str) -> str:
    """Convert any phone format to E.164."""
    digits = re.sub(r'\D', '', phone)
    if len(digits) == 10:
        return f"+1{digits}"
    elif len(digits) == 11 and digits[0] == '1':
        return f"+{digits}"
    return phone  # Return as-is if can't normalize

def has_consent(phone: str, message_type: str = "marketing") -> bool:
    """Check if a phone number has valid consent for this message type."""
    phone = normalize_phone(phone)

    # Query your database
    consent = db.query(
        "SELECT * FROM sms_consent WHERE phone_number = %s AND opted_out = FALSE",
        [phone]
    )

    if not consent:
        return False

    # Marketing requires explicit consent
    if message_type == "marketing":
        return consent.consent_type in ("marketing", "both") and consent.consent_given

    # Transactional messages have looser requirements
    if message_type == "transactional":
        return consent.consent_given

    return False

def send_sms(phone: str, message: str, message_type: str = "marketing"):
    """Send an SMS with compliance checks."""
    phone = normalize_phone(phone)

    # Check consent
    if not has_consent(phone, message_type):
        raise ValueError(f"No {message_type} consent for {phone}")

    # Ensure opt-out language is included in marketing messages
    if message_type == "marketing" and "STOP" not in message.upper():
        message += "\nReply STOP to unsubscribe"

    # Send via your provider (Twilio example)
    twilio_client.messages.create(
        body=message,
        from_=YOUR_TWILIO_NUMBER,
        to=phone
    )

    # Log the send
    db.execute(
        "INSERT INTO sms_log (phone, message, type, sent_at) VALUES (%s, %s, %s, %s)",
        [phone, message, message_type, datetime.utcnow()]
    )

OPT_OUT_KEYWORDS = {"stop", "unsubscribe", "cancel", "end", "quit"}
OPT_IN_KEYWORDS = {"start", "yes", "unstop"}

def handle_incoming_sms(from_number: str, body: str):
    """Process incoming SMS for opt-in/opt-out keywords."""
    normalized = body.strip().lower()
    phone = normalize_phone(from_number)

    if normalized in OPT_OUT_KEYWORDS:
        # Immediately opt out
        db.execute(
            """UPDATE sms_consent
               SET opted_out = TRUE, opted_out_at = NOW()
               WHERE phone_number = %s""",
            [phone]
        )
        # Send confirmation (required by TCPA)
        send_raw_sms(phone, "You've been unsubscribed and will no longer receive messages from us.")
        return {"action": "opted_out"}

    if normalized in OPT_IN_KEYWORDS:
        # Re-opt-in
        db.execute(
            """UPDATE sms_consent
               SET opted_out = FALSE, opted_out_at = NULL
               WHERE phone_number = %s""",
            [phone]
        )
        send_raw_sms(phone, "You've been re-subscribed. Reply STOP anytime to opt out.")
        return {"action": "opted_in"}

    return {"action": "message_received", "body": body}

from datetime import datetime
import pytz

def validate_sms(message: str, business_name: str, recipient_timezone: str = "US/Eastern"):
    """Validate an SMS message for compliance before sending."""
    errors = []

    # Check message length (SMS limit is 160 chars, or 1600 for long SMS)
    if len(message) > 1600:
        errors.append("Message exceeds 1600 character limit")

    # Check for business identification
    if business_name.lower() not in message.lower():
        errors.append(f"Message must include business name: {business_name}")

    # Check for opt-out language
    opt_out_phrases = ["reply stop", "text stop", "opt out", "unsubscribe"]
    has_opt_out = any(phrase in message.lower() for phrase in opt_out_phrases)
    if not has_opt_out:
        errors.append("Marketing messages must include opt-out instructions (e.g., 'Reply STOP to unsubscribe')")

    # Check sending hours (8 AM - 9 PM in recipient's timezone)
    tz = pytz.timezone(recipient_timezone)
    local_hour = datetime.now(tz).hour
    if local_hour < 8 or local_hour >= 21:
        errors.append(f"Outside sending hours in {recipient_timezone} (current: {local_hour}:00, allowed: 8:00-21:00)")

    return {"valid": len(errors) == 0, "errors": errors}

import requests

REBIRTH_HEADERS = {
    "Authorization": "Bearer rb_live_YOUR_KEY",
    "Content-Type": "application/json"
}

def send_compliant_follow_up(phone, industry, context, business_name, timezone="US/Eastern"):
    """Generate and send a compliant follow-up SMS."""

    # Step 1: Check consent
    if not has_consent(phone, "marketing"):
        return {"error": "No consent", "sent": False}

    # Step 2: Generate message with Rebirth API
    gen_resp = requests.post(
        "https://rebirthapi.com/api/v1/sms-generate",
        headers=REBIRTH_HEADERS,
        json={
            "type": "follow_up",
            "industry": industry,
            "context": context,
            "business_name": business_name
        }
    ).json()

    message = gen_resp["message"]

    # Step 3: Ensure compliance elements are present
    if "STOP" not in message.upper():
        message += " Reply STOP to opt out."

    # Step 4: Validate before sending
    validation = validate_sms(message, business_name, timezone)
    if not validation["valid"]:
        return {"error": validation["errors"], "sent": False}

    # Step 5: Send via Twilio
    send_sms(phone, message, message_type="marketing")

    return {"message": message, "sent": True}

# Usage
result = send_compliant_follow_up(
    phone="+15125551234",
    industry="hvac",
    context="Customer asked about AC repair pricing",
    business_name="CoolAir HVAC"
)
print(result["message"])
# "Hey! This is CoolAir HVAC following up on your AC question.
#  We're running a spring tune-up special — want a free estimate?
#  Reply YES or call (512) 555-0000. Reply STOP to opt out."