# Deliverability

Source: https://joinsimplesms.com/docs/deliverability
Index: https://joinsimplesms.com/llms.txt

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](/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

```bash
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_..."
```

| Parameter | Default | Notes |
| --- | --- | --- |
| `group_by` | `day` | `day`, `carrier`, or `number` |
| `start_date` | 6 days before `end_date` | `YYYY-MM-DD`, UTC, inclusive |
| `end_date` | today | `YYYY-MM-DD`, UTC, inclusive. Ranges are limited to 90 days. |

```json
{
  "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](/docs/webhooks),
- and alert our team.

```json
{
  "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.