SMS Notifications via API (Twilio teaser)

By the end of this lesson you can:

• Explain when SMS is the right channel (and when it's overkill).
• Understand the Twilio account model: SID, auth token, from-number.
• Send an SMS with the Twilio API (and via raw requests).
• Add SMS as a channel in your notifier, gated to high-severity only.

Channel    Speed     Cost      Use for
log file   instant   free      everything (the record)
Slack      seconds   free      team-visible status, most alerts
email      minutes   free      reports, daily digests
SMS        instant   ~cents    CRITICAL only — server down at 3am

The account model

Twilio (the common SMS API; alternatives include Vonage, MessageBird) gives you three things stored in your .env:

TWILIO_ACCOUNT_SID   your account id   (like a username)
TWILIO_AUTH_TOKEN    your secret token (like a password)
TWILIO_FROM          a Twilio phone number you send FROM

A free trial gives credit and a sandbox number that can text verified phones — enough to learn without spending real money.

With the official library

import os
from twilio.rest import Client           # pip install twilio
from dotenv import load_dotenv

load_dotenv()
client = Client(os.environ["TWILIO_ACCOUNT_SID"],
                os.environ["TWILIO_AUTH_TOKEN"])

message = client.messages.create(
    body="🚨 CRITICAL: web server is down",
    from_=os.environ["TWILIO_FROM"],
    to="+60123456789",                    # E.164 format: +<country><number>
)
print("sent, sid:", message.sid)

The library wraps the HTTP calls. Phone numbers must be in E.164 format (+ country code, no spaces). Keep messages short — SMS bills per 160-character segment.

The same thing with raw requests

Under the hood it's just an authenticated POST — useful to see, and avoids the dependency:

import os, requests

def send_sms(to: str, body: str) -> bool:
    sid = os.environ["TWILIO_ACCOUNT_SID"]
    url = f"https://api.twilio.com/2010-04-01/Accounts/{sid}/Messages.json"
    resp = requests.post(
        url,
        auth=(sid, os.environ["TWILIO_AUTH_TOKEN"]),   # HTTP basic auth
        data={"From": os.environ["TWILIO_FROM"],
              "To": to, "Body": body[:1500]},
        timeout=15,
    )
    return resp.status_code == 201        # 201 Created on success

It's the OAuth/credentials pattern from Lesson 25: secrets from the environment, HTTP basic auth (auth=(sid, token)), a form-encoded POST, and a status-code check. Every paid API looks roughly like this.

Goal: add SMS to the unified notifier from Lesson 32, but only for CRITICAL alerts — with a rate guard so a runaway loop can't empty your wallet.

import os, time, json, logging, requests
from pathlib import Path
from dotenv import load_dotenv

load_dotenv()
logging.basicConfig(level=logging.INFO, format="%(levelname)s %(message)s")
log = logging.getLogger("sms")

RATE_FILE = Path(".sms_rate.json")
MAX_PER_HOUR = 5                          # hard cap to protect your bill

def _sent_last_hour() -> int:
    if not RATE_FILE.exists():
        return 0
    times = json.loads(RATE_FILE.read_text())
    recent = [t for t in times if t > time.time() - 3600]
    RATE_FILE.write_text(json.dumps(recent))     # prune old entries
    return len(recent)

def _record_send() -> None:
    times = json.loads(RATE_FILE.read_text()) if RATE_FILE.exists() else []
    times.append(time.time())
    RATE_FILE.write_text(json.dumps(times))

def send_sms(to: str, body: str) -> bool:
    if _sent_last_hour() >= MAX_PER_HOUR:
        log.error("SMS rate cap (%d/hr) hit — refusing to send", MAX_PER_HOUR)
        return False
    sid = os.environ["TWILIO_ACCOUNT_SID"]
    try:
        r = requests.post(
            f"https://api.twilio.com/2010-04-01/Accounts/{sid}/Messages.json",
            auth=(sid, os.environ["TWILIO_AUTH_TOKEN"]),
            data={"From": os.environ["TWILIO_FROM"], "To": to,
                  "Body": body[:300]},
            timeout=15)
        if r.status_code == 201:
            _record_send()
            log.info("SMS sent to %s", to)
            return True
        log.error("SMS failed: %s %s", r.status_code, r.text[:120])
    except requests.RequestException as e:
        log.error("SMS error: %s", e)
    return False

def alert(text: str, level: str = "info") -> None:
    # …Slack/Discord for all levels (Lesson 32)…
    if level == "critical":
        to = os.getenv("ONCALL_PHONE")
        if to:
            send_sms(to, f"CRITICAL: {text}")
        else:
            log.warning("critical alert but no ONCALL_PHONE set")

alert("Disk at 88%", "warning")          # Slack/Discord only
alert("Database unreachable", "critical") # also fires SMS (if under cap)

INFO SMS sent to +60123456789
# A 6th critical within the hour:
ERROR SMS rate cap (5/hr) hit — refusing to send

Read the code

Two safeguards make this safe to deploy: SMS only fires for level == "critical" (everything else stays on free channels), and a persisted rate guard refuses to send more than MAX_PER_HOUR — so a buggy loop costs you 5 texts, not 5,000. The send itself is the familiar credentials-from-env, basic-auth POST. This is the SMS channel that plugs into Lesson 34's multi-channel alert system, where routing rules decide what goes where.

A Twilio free trial is enough to try this on your own verified phone. If you'd rather not sign up, simulate it: write the same functions but have send_sms just log.info("SMS → %s: %s") instead of calling the API — the surrounding logic (gating, rate cap) is what matters.

for i in range(8):
    ok = send_sms("+60123456789", f"test {i}")
    print(i, "sent" if ok else "BLOCKED")

def route(text, level):
    slack_log(text, level)                     # always
    if level in ("error", "critical"):
        email_alert(text, level)
    if level == "critical":
        send_sms(os.getenv("ONCALL_PHONE"), text)

SMS (via Twilio or similar) is the instant, intrusive, paid channel — reserve it for CRITICAL alerts. Technically it's the same API pattern you know: SID/auth-token/from-number from the environment, an authenticated POST, numbers in E.164 format, short bodies. The discipline is what's new: gate SMS to high severity, add a hard rate cap so a bug can't drain your account, only text people who consented, and consider an escalation ladder (Slack → email → SMS). SMS becomes one more adapter in your notifier — used sparingly. Next lesson assembles all channels into a routed alert system.