Deliverability

Every final outcome of an outbound message (delivered or failed) is counted by day, by the recipient's carrier, and by the number you sent from. Read the numbers from the API, or open Console → Deliverability for trends, your worst carriers and numbers, and a breakdown of failure reasons.

Test keys report sandbox traffic; live keys report live traffic. Counts only: no message content is part of this data.

GET /v1/deliverability

curl "https://api.joinsimplesms.com/v1/deliverability?group_by=carrier&start_date=2026-09-01&end_date=2026-09-30" \
  -H "Authorization: Bearer ssms_sk_live_..."

{
  "object": "deliverability",
  "mode": "live",
  "start_date": "2026-09-01",
  "end_date": "2026-09-30",
  "group_by": "carrier",
  "totals": { "key": "total", "delivered": 9412, "failed": 88, "total": 9500, "delivery_rate": 0.9907,
              "failure_reasons": { "unknown_subscriber": 51, "carrier_violation": 37 } },
  "data": [
    { "key": "example_wireless", "delivered": 2100, "failed": 61, "total": 2161, "delivery_rate": 0.9718,
      "failure_reasons": { "carrier_violation": 37, "unknown_subscriber": 24 } }
  ]
}

day rows come back in date order; carrier and number rows worst first. The carrier is known when the recipient has been looked up recently (GET /v1/lookup); otherwise it is unknown. Numbers are keyed by their 10 digits. Needs the messages:read scope on a restricted key.

Degradation alerts

Every 15 minutes we compare each account's last 2 hours with its previous 7 days, for all traffic, each carrier, and each sending number. When the delivery rate falls sharply (at least 15 points and at least 20% below normal, with at least 20 recent and 100 baseline outcomes, so a handful of failures can't trigger it), we:

• show the alert at the top of the Deliverability page,
• send a deliverability.degraded webhook event,
• and alert our team.

{
  "type": "deliverability.degraded",
  "data": {
    "alert_id": "dal_...",
    "dimension": "number",
    "key": "4155550132",
    "window_rate": 0.41,
    "baseline_rate": 0.97,
    "window_total": 230,
    "baseline_total": 18400,
    "window_hours": 2
  }
}

dimension is account (all traffic), carrier, or number. Each series alerts at most once every 6 hours.