Web-Based Subscription Management

Public API endpoints for opt-in/opt-out via web links, designed for alphanumeric sender IDs that cannot receive SMS replies.

New Feature: Allows users to manage their SMS subscriptions via web browser when SMS replies are not possible.

Overview

This API provides public (no authentication required) endpoints that allow users to opt-in or opt-out of SMS communications by clicking a link in their browser. This is essential for alphanumeric sender IDs (e.g., "SchoolSMS", "BankAlert") that cannot receive SMS replies.

The Problem

Numeric Channels (Works)

Example: Short code 44880

User receives: "Promo from 44880"
User replies: "STOP" to 44880
System processes opt-out ✅

Alphanumeric Channels (Broken)

Example: Sender ID SchoolSMS

User receives: "Alert from SchoolSMS"
User tries to reply: "STOP"
Message fails - alphanumeric IDs are send-only ❌

The Solution

Include a web link in your SMS messages that users can click to manage their subscription:

SchoolSMS: Your child has been marked absent today.
To opt-out: https://sms.com.na/u/abc123

When the user clicks the link, they see a beautiful confirmation page and their subscription status is updated immediately.

API Endpoints

Opt-Out Endpoint

GET https://{host}/sms/2/messages/subscription/{clientid}/opt/out/{mobile}

Path Parameters

Parameter	Type	Required	Description
`clientid`	integer	Yes	Your client ID (e.g., 1000)
`mobile`	string	Yes	Mobile number to opt-out (e.g., 0812345678)

Example Request

GET https://{host}/sms/2/messages/subscription/1000/opt/out/0812345678

Success Response (200 OK)

Returns a beautiful HTML confirmation page:

<!DOCTYPE html>
<html>
<head>
    <title>Successfully Opted Out - SMS.COM.NA</title>
    <!-- Modern, responsive design -->
</head>
<body>
    <div class="container">
        <div class="icon success">✓</div>
        <h1>Successfully Opted Out</h1>
        <p>You have successfully opted out from SchoolSMS. 
           You will no longer receive SMS messages from us.</p>
    </div>
</body>
</html>

Error Responses

Status Code	Reason	Response
400	Invalid URL format	HTML page with error message
400	Invalid client ID	HTML page with error message
404	Client not found	HTML page with error message
500	Processing error	HTML page with error message

Opt-In Endpoint

GET https://{host}/sms/2/messages/subscription/{clientid}/opt/in/{mobile}

Path Parameters

Parameter	Type	Required	Description
`clientid`	integer	Yes	Your client ID (e.g., 1000)
`mobile`	string	Yes	Mobile number to opt-in (e.g., 0812345678)

Example Request

GET https://{host}/sms/2/messages/subscription/1000/opt/in/0812345678

Success Response (200 OK)

Returns a beautiful HTML confirmation page:

<!DOCTYPE html>
<html>
<head>
    <title>Successfully Opted In - SMS.COM.NA</title>
</head>
<body>
    <div class="container">
        <div class="icon success">✓</div>
        <h1>Successfully Opted In</h1>
        <p>You have successfully opted in to receive messages from SchoolSMS. 
           You will now receive SMS communications.</p>
    </div>
</body>
</html>

Response Pages

All responses are rendered as beautiful, mobile-responsive HTML pages with:

Mobile-first design - Optimized for smartphones
Modern UI - Clean, professional appearance
Clear feedback - Success/error icons and messages
Branded - SMS.COM.NA logo and colors

How to Compose SMS Messages with Opt-Out Links

Important: The opt-out link must be included in every marketing SMS for legal compliance.

SMS Message Structure

Follow this proven structure for maximum clarity and compliance:

Recommended Format:

[Sender Name]: [Your message content here]
[Optional: Call-to-action or link]
[Opt-out instruction]: [Short URL]

Character Count:
- Message content: 100-120 characters
- Opt-out line: 30-40 characters
- Total: 130-160 characters (fits in 1 SMS)

✅ Good Examples

Example 1: School Alert (Perfect)
SchoolSMS: Your child has been marked absent today. 
Please contact the school office.
Opt-out: https://sms.com.na/u/sch123

Why it works:
✓ Clear sender identification
✓ Concise message
✓ Opt-out at the end
✓ Short URL saves characters
✓ Total: 128 characters (1 SMS)

Example 2: Marketing Promotion (Perfect)
BankAlert: 50% OFF on all loans this month! 
Apply now: bank.com/loans
Unsubscribe: https://sms.com.na/u/bnk456

Why it works:
✓ Attention-grabbing offer
✓ Clear call-to-action
✓ Professional unsubscribe option
✓ Total: 115 characters (1 SMS)

Example 3: Appointment Reminder (Perfect)
ClinicSMS: Reminder - Dr. Smith appointment tomorrow at 2pm.
Reply CONFIRM or CANCEL.
Manage alerts: https://sms.com.na/u/cli789

Why it works:
✓ Clear appointment details
✓ Interactive options
✓ Manage alerts (softer than "opt-out")
✓ Total: 134 characters (1 SMS)

❌ Bad Examples (Avoid These)

Example 1: URL Too Long (Wastes Characters)
SchoolSMS: Your child has been marked absent.
Opt-out: https://{host}/sms/2/messages/subscription/1000/opt/out/0812345678

Problems:
❌ Long URL wastes 78 characters
❌ Looks unprofessional
❌ May break across lines
❌ Total: 156 characters (barely fits)

Example 2: Opt-Out at Beginning (Confusing)
Opt-out: https://sms.com.na/u/abc123
SchoolSMS: Your child has been marked absent today.

Problems:
❌ User sees opt-out before message
❌ May opt-out without reading
❌ Looks like spam

Example 3: No Clear Opt-Out (Non-Compliant)
SchoolSMS: Your child has been marked absent today.
More info: https://sms.com.na/u/abc123

Problems:
❌ Link purpose unclear
❌ Not obviously an opt-out
❌ May violate regulations

Example 4: Manual Placeholder (User-Hostile)
SchoolSMS: Your child has been marked absent.
Opt-out: https://{host}/sms/2/messages/subscription/1000/opt/out/{mobile}

Problems:
❌ User must manually replace {mobile}
❌ Too technical for average user
❌ Poor user experience

Opt-Out Wording Options

Choose wording that matches your brand voice:

Wording	Tone	Best For
`Opt-out: [link]`	Neutral	General purpose, professional
`Unsubscribe: [link]`	Formal	Marketing, newsletters
`Stop SMS: [link]`	Direct	Transactional messages
`Manage alerts: [link]`	Friendly	Service notifications
`No more alerts: [link]`	Casual	Informal communications
`Click here: [link]`	Vague	❌ Avoid - unclear purpose

Character Optimization Tips

Do This

Use URL shorteners (25 chars vs 78 chars)
Abbreviate where appropriate: "Dr." not "Doctor"
Use numerals: "2pm" not "two o'clock"
Keep sender name short: "SchoolSMS" not "School SMS System"
Place opt-out at the end

Don't Do This

Use long URLs (wastes 50+ characters)
Add unnecessary words: "Please kindly..."
Repeat sender name in message
Use multiple links
Add emojis (may not render correctly)

Multi-Part SMS Considerations

Cost Warning: Messages over 160 characters are split into multiple SMS and cost more!

Message Length	SMS Parts	Cost Multiplier	Recommendation
1-160 characters	1 SMS	1x	✅ Ideal - Keep messages here
161-306 characters	2 SMS	2x	⚠️ Acceptable for important messages
307-459 characters	3 SMS	3x	❌ Too expensive - shorten message

Legal Compliance Checklist

Before Sending Marketing SMS

☐ Opt-out link included in every message
☐ Opt-out link is clearly labeled
☐ Link is functional and tested
☐ Sender ID clearly identifies your brand
☐ Message content is relevant to recipient
☐ Recipient has previously opted in (for marketing)
☐ Message sent during business hours (8am-8pm)
☐ Total character count optimized (ideally <160)< /li>

Configuration

Step 1: Configure Your Channel

Log in to the SMS.COM.NA Portal
Navigate to Account → SMS Channels
Select your alphanumeric channel (e.g., "SchoolSMS")
Scroll to "Opt-out Link for Alphanumeric Channels"
The default base URL is pre-filled: https://{host}/sms/2/messages/subscription/
Click "Save Settings"

Step 2: Get Your Links

The portal will generate your opt-out and opt-in links:

Opt-Out Link:
https://{host}/sms/2/messages/subscription/{clientid}/opt/out/{mobile}

Opt-In Link:
https://{host}/sms/2/messages/subscription/{clientid}/opt/in/{mobile}

Replace {clientid} with your client ID and {mobile} with the recipient's number.

Step 3: Use Custom Opt-Out Page (Optional)

If you have your own subscription management portal:

Leave the "Opt-out Link Base URL" field blank
Use your own URL in SMS messages
Your page should call our API to update the database

URL Shortening

Important: Long URLs waste SMS characters. Always use URL shortening for production!

Why Shorten URLs?

Type	URL	Characters	% of SMS
Long URL	`https://{host}/sms/2/messages/subscription/1000/opt/out/0812345678`	78	49%
Short URL	`https://sms.com.na/u/abc123`	25	16%
Savings		53 chars	33%

Recommended URL Shorteners

Bitly

bitly.com

API available
Custom domains
Analytics

TinyURL

tinyurl.com

Simple API
Free tier
No registration

Custom Domain (Recommended)

sms.com.na/u/{code}

Professional branding
Full control
Trust & recognition

Usage Examples

Example 1: School Notifications

SMS Message:
SchoolSMS: Your child has been marked absent today. 
Please contact the school office.
Opt-out: https://sms.com.na/u/sch123

Generated Link:
https://sms.com.na/u/sch123 
  → https://{host}/sms/2/messages/subscription/1000/opt/out/0812345678

Example 2: Marketing Campaign

SMS Message:
BankAlert: 50% OFF on all loans this month! 
Apply now: bank.com/loans
Unsubscribe: https://sms.com.na/u/bnk456

Generated Link:
https://sms.com.na/u/bnk456
  → https://{host}/sms/2/messages/subscription/1000/opt/out/0813456789

Example 3: Appointment Reminders

SMS Message:
ClinicSMS: Reminder - Dr. Smith appointment tomorrow at 2pm.
Reply CONFIRM or CANCEL.
Manage alerts: https://sms.com.na/u/cli789

Generated Link:
https://sms.com.na/u/cli789
  → https://{host}/sms/2/messages/subscription/1000/opt/out/0814567890

Example 4: Programmatic URL Generation

// C# Example
public string GenerateOptOutLink(int clientId, string mobile)
{
    string longUrl = $"https://{host}/sms/2/messages/subscription/{clientId}/opt/out/{mobile}";
    
    // Use Bitly API to shorten
    string shortUrl = await BitlyService.ShortenUrl(longUrl);
    
    return shortUrl; // https://bit.ly/abc123
}

// Usage in SMS
string message = $@"SchoolSMS: Your child has been marked absent.
Opt-out: {GenerateOptOutLink(1000, "0812345678")}";

SMS-Based vs Web-Based Opt-Out

Feature	SMS-Based (Numeric)	Web-Based (Alphanumeric)
User Action	Reply "STOP" to SMS	Click link in SMS
Channel Type	Numeric short codes only	Alphanumeric sender IDs
Authentication	None (SMS is proof)	None (link is proof)
Confirmation	Auto-reply SMS	Beautiful web page
Cost	1 SMS credit (reply)	Free (web request)
User Experience	Simple, familiar	Modern, visual
Webhook Support	Yes (if configured)	No (future enhancement)

Best Practices

Best Practices for Web-Based Subscription Management

1. Always Use URL Shortening

Long URLs waste precious SMS characters
Short URLs look more professional
Easier for users to read and trust

2. Personalize Each Link

Generate unique short URLs for each recipient
Include mobile number in the target URL
Track click-through rates per campaign

3. Place Link at End of Message

✅ Good:
SchoolSMS: Your child has been marked absent.
Opt-out: https://sms.com.na/u/abc123

❌ Bad:
Opt-out: https://sms.com.na/u/abc123
SchoolSMS: Your child has been marked absent.

4. Use Clear Call-to-Action

Opt-out: [link] ✅
Unsubscribe: [link] ✅
Stop SMS: [link] ✅
[link] ❌ (unclear purpose)

5. Test Before Sending

Generate test links with your mobile number
Click the link and verify the confirmation page
Check database to confirm status update
Try sending SMS to opted-out number (should be blocked)

6. Monitor Opt-Out Rates

Track opt-outs per campaign
High opt-out rate = content not relevant
Adjust targeting and messaging accordingly

7. Provide Opt-In Link Too

Allow users to re-subscribe easily
Include opt-in link on your website
Send opt-in link in email confirmations

8. Comply with Regulations

Include opt-out link in every marketing SMS
Process opt-outs immediately (our system does this automatically)
Never send SMS to opted-out contacts
Keep audit trail of all opt-in/opt-out actions

Security & Privacy

No Authentication Required

The opt-out/opt-in endpoints are intentionally public because:

User Convenience: Users shouldn't need to log in to opt-out
Legal Compliance: Opt-out must be frictionless
Limited Risk: Only allows changing subscription status, not accessing data

Mobile Number Normalization

The system normalizes mobile numbers to prevent bypassing:

// All these formats map to the same contact:
0812345678
+264812345678
264812345678
081-234-5678
(081) 234-5678

Audit Trail

Every opt-in/opt-out action is logged in the database:

mobile       | status | status_description                        | auddate
-------------|--------|-------------------------------------------|-------------------
0812345678   | 0      | OPTED OUT - 2026-07-21 13:45:00 UTC - Web request | 2026-07-21 13:45:00

Web-Based Subscription Management

Overview

The Problem

Numeric Channels (Works)

Alphanumeric Channels (Broken)

The Solution

API Endpoints

Opt-Out Endpoint

Path Parameters

Example Request

Success Response (200 OK)

Error Responses

Opt-In Endpoint

Path Parameters

Example Request

Success Response (200 OK)

Response Pages

How to Compose SMS Messages with Opt-Out Links

SMS Message Structure

✅ Good Examples

❌ Bad Examples (Avoid These)

Opt-Out Wording Options

Character Optimization Tips

Do This

Don't Do This

Multi-Part SMS Considerations

Legal Compliance Checklist

Before Sending Marketing SMS

Configuration

Step 1: Configure Your Channel

Step 2: Get Your Links

Step 3: Use Custom Opt-Out Page (Optional)

URL Shortening

Why Shorten URLs?

Recommended URL Shorteners

Bitly

TinyURL

Custom Domain (Recommended)

Usage Examples

Example 1: School Notifications

Example 2: Marketing Campaign

Example 3: Appointment Reminders

Example 4: Programmatic URL Generation

SMS-Based vs Web-Based Opt-Out

Best Practices

Best Practices for Web-Based Subscription Management

1. Always Use URL Shortening

2. Personalize Each Link

3. Place Link at End of Message

4. Use Clear Call-to-Action

5. Test Before Sending

6. Monitor Opt-Out Rates

7. Provide Opt-In Link Too

8. Comply with Regulations

Security & Privacy

No Authentication Required

Mobile Number Normalization

Audit Trail

Support & Resources

Documentation

Support

Code Examples