Skip to main content
SMS subscriptions let your users receive critical status updates as text messages. This is especially valuable for users who need to know about outages immediately, even when they’re away from email.

​
How It Works

  1. User enters phone number on your status page
  2. They receive a verification code via SMS
  3. After verifying, they receive SMS for incidents matching their preferences
  4. Users can unsubscribe anytime by replying STOP

​
Enabling SMS Subscriptions

  1. Go to Dashboard → Settings → Subscribers
  2. Enable SMS Subscriptions
  3. Configure Twilio credentials (see below)
  4. Customize the verification message
  5. Save settings

​
Twilio Setup

Kodo uses Twilio for SMS delivery. You’ll need:
  1. Twilio Account SID: Found in your Twilio Console
  2. Twilio Auth Token: Your API authentication token
  3. Phone Number: A Twilio phone number to send from
# Set via CLI
kodo config set twilio.account_sid "ACXXXXXXXXXX"
kodo config set twilio.auth_token "your_auth_token"
kodo config set twilio.phone_number "+15551234567"
SMS costs apply based on your Twilio pricing. Each verification and notification counts as a message.

​
Subscriber Management

​
View SMS Subscribers

kodo subscribers list --type sms

# Output:
# Phone           | Verified | Subscribed
# +1555123xxxx    | Yes      | 2024-01-15
# +1555456xxxx    | Yes      | 2024-01-10
# +1555789xxxx    | No       | (pending verification)

​
Subscriber Preferences

SMS subscribers can choose what to receive:
PreferenceDefaultDescription
All incidentsYesAll new incidents
Critical onlyNoOnly critical severity
Specific servicesNoOnly selected services
ResolutionsYesWhen incidents resolve
MaintenanceNoScheduled maintenance notices

​
Manually Add Subscriber

For internal teams or VIP customers: 
curl -X POST "https://kodostatus.com/api/sms/subscribers" \
  -H "X-API-Key: your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "sms",
    "phone": "+15551234567",
    "verified": true,
    "preferences": {
      "severity_filter": ["critical", "major"],
      "services": ["svc_api", "svc_payments"]
    }
  }'

​
SMS Message Templates

Customize the messages your subscribers receive:

​
Incident Created

Default: [Kodo] {{severity}} incident: {{title}}

Custom example:
[YourApp] {{severity}}: {{title}}. Updates at status.yourapp.com

​
Incident Updated

Default: [Kodo] Update: {{title}} - {{status}}

Custom example:
[YourApp] {{title}} is now {{status}}

​
Incident Resolved

Default: [Kodo] Resolved: {{title}}

Custom example:
[YourApp] All clear: {{title}} resolved

​
Available Variables

VariableDescription
{{title}}Incident title
{{severity}}critical, major, minor
{{status}}investigating, identified, monitoring, resolved
{{message}}Latest update message
{{service}}Affected service name
{{url}}Link to status page

​
International SMS

Kodo supports international phone numbers:
  • Numbers are validated before sending
  • Country codes are required (+1 for US, +44 for UK, etc.)
  • Delivery rates vary by country
  • Some countries have regulatory requirements
For compliance in certain regions (EU, India, etc.), you may need to register your Twilio number as a verified sender.

​
Unsubscribing

Users can unsubscribe by:
  1. Replying STOP: Standard SMS opt-out
  2. Status page: Click “Manage Subscription” link
  3. API: You can remove subscribers programmatically
curl -X DELETE "https://kodostatus.com/api/sms/subscribers?id=sub_abc123" \
  -H "X-API-Key: your_api_key"

​
Rate Limits & Best Practices

Keep messages under 160 characters to avoid splitting into multiple SMS (which costs more).
Don’t spam subscribers. Combine rapid updates into fewer messages where possible.
Consider time zones—avoid sending non-critical updates at 3 AM.
Verification codes expire after 10 minutes. Unverified subscribers are removed after 24 hours.
Ensure you have consent before adding subscribers. Keep records of opt-ins for TCPA compliance.

​
Troubleshooting

​
Messages not delivering?

  1. Check Twilio dashboard for delivery errors
  2. Verify phone number format includes country code
  3. Ensure Twilio account has sufficient balance
  4. Check if number is on a carrier blocklist

​
Verification codes not received?

  1. Confirm phone number is correct
  2. Check for carrier filtering (common with short codes)
  3. Try resending after a few minutes
  4. Contact support if issues persist