SMS Deliverability Triage Playbook

This playbook enables you to diagnose why SMS messages are not being delivered and to apply the correct fix in the correct order. The target end state is a working SMS delivery pipeline where messages reach recipients, delivery failures are visible and explainable, and the system does not silently drop traffic.

The operational reason for this work is that undiagnosed SMS delivery failures waste money on undeliverable messages, damage sender reputation with carriers, and create silent gaps in time-sensitive operational communications — order notifications, appointment reminders, alerts, and verification codes.

The systems affected are your SMS sending platform (Twilio, MessageBird, or equivalent), your A2P 10DLC registration records, your suppression list, and your opt-in capture flow.

Success criteria

• Every undelivered message has a traceable failure reason.
• Suppression, registration, throttling, reputation, and opt-in checks happen before a message is queued for sending.
• The sending quota and throughput are known and monitored.
• Carriers receive signals that the sender is legitimate, which protects long-term deliverability.
• The diagnostic sequence is repeatable and documented.

Decisions

Before beginning, confirm the following with the person who owns the SMS account:

1. Who owns the A2P 10DLC registration? If it is an external agency or a prior vendor, you need their contact before you can verify registration status.
2. What is the sending volume per day? This determines whether throttling is a plausible cause.
3. What is the source of truth for opt-in status? If consent is stored in multiple systems, you must identify which one governs sending.
4. Who is the escalation contact at the SMS provider? Some fixes, such as reputation repair, require provider-side action.

The implementation relies on the following capabilities. Specific products are named only where the source supports it; otherwise, the required capability is described.

• SMS sending platform: The service that actually sends messages and returns delivery status. Examples include Twilio, MessageBird, and similar providers. You must be able to query per-message status and error codes. If your platform does not expose per-message error codes, stop — you cannot diagnose delivery failures without them, and you need to request access or change platforms first.
• A2P 10DLC registration: An industry registration required in the US and Canada for sending application-to-person messages over 10-digit long codes. Your sending platform exposes the campaign and brand registration status, and the carrier vetting status.
• Suppression list: A record of numbers that must never receive a message. This may live inside your SMS platform, in your customer database, or both.
• Opt-in records: Proof that each recipient consented to receive messages. This may be stored in your CRM, a consent database, or the SMS platform itself.
• Monitoring or log aggregation (optional but recommended): A place where the diagnostic result of each outbound message is recorded, so the triage loop can be verified over time.

What this step does

Before changing anything, you need the full picture of what is failing. This step gathers the raw evidence: which messages failed, when, and with what carrier error code. Without this, every later diagnosis is a guess.

Actions

1. 1

   Export failure logs

   Export or query the delivery logs from the SMS platform for the last 7 days. Filter for messages with a final status other than delivered.
   Record the following fields for each failed message:

2. 2

   Record failure fields

   Message identifier (SID or equivalent)
   Recipient number
   Timestamp
   Final status (e.g., undelivered, failed, blocked, sent without a delivery receipt)
   Carrier error code and message

3. 3

   Group by error code

   Group the failures by carrier error code. Common families include:

4. 4

   Compute failure rate

   Compute the failure rate as a percentage of total messages sent in the same period.
   If the logs are not accessible or do not contain per-message error codes, stop here and request the necessary access. Do not proceed on guesswork.

• 30007-family errors: opt-out or carrier block
• Errors indicating invalid or unreachable numbers
• Errors indicating throttling or rate limits
• Errors indicating carrier rejection on reputation grounds

Important considerations

What this step does

The most common cause of undelivered SMS is that the recipient opted out or was added to a blocklist, and the sending system still attempted to send. This step confirms whether the suppression list was checked and whether the affected numbers are on it.

Actions

1. Export the suppression list. Include phone numbers, the reason for suppression (opt-out, carrier block, complaint), and the date added.
2. Take a sample of 50 failed recipient numbers from Step 1 and compare them against the suppression list.
3. If any match, the sending flow is not checking suppression before queueing. That is the root cause for those messages.
4. Check the sending logic or workflow to confirm whether a suppression check exists at all. Look for a step that queries the blocklist before sending.
5. If the suppression check exists, verify it is querying the same list you just exported. A common failure is that the application checks a stale or partial list.

Important considerations

What this step does

In the US and Canada, messages sent to 10-digit long codes without a registered, approved A2P 10DLC campaign are routinely filtered or blocked by carriers. This step confirms whether your campaign registration is approved and whether the messages are associated with it.

Actions

1. Query the A2P 10DLC registration status in the SMS platform. Record the brand status, campaign status, and the campaign ID.
2. Confirm that the phone number used for sending is associated with that brand and campaign. A common failure is sending from a number that was never attached to the campaign.
3. Check that the messages in your failed log were sent from the registered number. If the sending system can use multiple numbers, confirm none of the affected traffic used an unregistered number.
4. If the campaign status is pending or rejected, that explains carrier filtering. Note which status it is.
5. If the campaign was approved but the failure persists, record the campaign ID and carrier error codes. These two pieces of evidence are what you will send to the provider if reputation is implicated later.

Important considerations

• A2P 10DLC is a US/Canada requirement. If the affected messages are going to other countries, this step does not apply to those destinations. Do not waste time chasing a registration that does not govern the traffic.
• Your SMS platform may show the registration as approved by the platform but still pending carrier vetting. These are different. The platform approval does not guarantee carrier acceptance.
• If the registration is rejected, the fix is not something you can deploy in code. It requires correcting the registration and resubmitting. Route that to the registration owner.

What this step does

Carriers and SMS platforms enforce throughput limits. If you send faster than the allowed rate, messages queue, back up, and eventually fail or are dropped. This step checks whether the failure pattern matches a throttle.

Actions

1. Find your platform's documented throughput limit for the account (messages per second) and any per-number limit.
2. Compare your actual send rate during the failure window against the limit. Use the timestamps from Step 1 to estimate the peak rate.
3. Look at the failure distribution over time. A throttle typically produces a burst of failures at a specific high-volume moment, not a steady trickle.
4. Check whether the sending system has any retry logic and how it behaves under load. If there is no backoff, a retry storm can amplify throttling.
5. If throttling is confirmed, identify whether the limit is platform-side or carrier-side. Platform-side limits are within your control; carrier-side limits may require a dedicated short code or a higher-tier agreement for sustained volume.

Important considerations

What this step does

If the messages passed the previous four checks and still fail, the cause may be carrier-side reputation filtering. Carriers track the sending history of a phone number, and a history of complaints, high bounce rates, or spam reports downgrades the number's trust. This step determines whether reputation is implicated and whether it can be repaired.

Actions

1. Review the complaint rate and spam-report rate for the sending number over the last 30 days, if the platform exposes it.
2. Review the number's bounce rate (invalid or unreachable numbers). A high bounce rate lowers reputation quickly.
3. Check whether the destination carriers that are failing are a small set or a broad set. Reputation filtering often produces failures concentrated on specific carriers, because each carrier maintains its own reputation for the sender.
4. If reputation is implicated, do not attempt to repair it by sending more volume. That makes it worse.
5. To recover reputation, stop sending to the problem carriers temporarily, clean the list of invalid numbers, and resume with low, consistent volume that is fully authorized. The recovery window is typically a matter of weeks, not days.
6. If the reputation issue is severe, escalate to the SMS provider and provide the campaign ID and carrier error codes. Some providers can investigate carrier-side blocks that you cannot see.

Important considerations

What this step does

If suppression, registration, throttling, and reputation are all clear, the remaining common cause is that the recipient never consented, or the sending system cannot prove consent. Carriers and platforms are increasingly filtering traffic that cannot show a valid opt-in record. This step verifies the opt-in state of the affected recipients.

Actions

1. Take a sample of 50 failed recipients from Step 1 and look up their opt-in record.
2. Confirm the opt-in record contains the recipient's phone number, the timestamp of consent, and the consent channel (web form, SMS keyword, in-app).
3. Check whether the consent record matches the data the sending system should be checking. If consent lives in your CRM but the sending platform checks its own record, the two may disagree.
4. If a meaningful share of the sampled recipients have no valid opt-in record, the sending flow is not gating on consent. That is a compliance gap, and it also explains carrier filtering, because carriers look for sender behavior consistent with consent-based messaging.
5. If the consent records exist and are valid, then opt-in is not the cause, and you should return to carrier error codes with the provider.

Important considerations

After the fixes are applied, validate the complete system, not just individual checks.

Functional behavior

1. Send a test message to a number known to be on the suppression list. Confirm it is blocked before reaching the carrier, and record the blocking reason.
2. Send a test message to a number with a valid opt-in record and confirmed registration. Confirm it reaches the carrier and returns a delivery receipt.
3. Send to a number that has never opted in. Confirm it is rejected at the pre-send gate.

Data correctness

1. Export the suppression list and confirm the test number used in step 1 is still on it. The check must not have modified the list.
2. Confirm the opt-in record for the valid test number is unchanged after sending.

Permissions

1. Confirm only the service account or credentials used by the sending flow can read and write the suppression list.
2. Confirm no credential used by the sending flow has broader permissions than it requires.

Failure behavior

1. Temporarily disable the suppression-list lookup (or use a test mode that simulates an unavailable dependency) and confirm the sending flow fails visibly with an error rather than sending without the check.
2. Confirm that a throttled or rate-limited message is retried with backoff and eventually fails cleanly, rather than being sent multiple times in a tight loop.

Observability

1. Confirm the sending flow logs the result of each of the five checks (suppression, registration, throttle, reputation, consent) for every outbound message.
2. Confirm failure reasons are visible in the log aggregation or monitoring system.

Repeatability

1. Run the full validation sequence twice. Confirm the second run does not produce duplicate messages or double-sends for the test records.

Production readiness

1. Confirm the flow operates without manual intervention across all five checks.
2. Confirm the monitoring dashboard shows the checks passing or failing in real time.

Rollback

The fixes in this playbook are primarily configuration and logic changes, so rollback depends on what you changed:

• Suppression check added: If the new check produces false positives (blocking valid traffic), the rollback is to remove or disable the check. Do this only after confirming the false-positive pattern, and keep the suppression list intact.
• Registration changes: If you changed the sending number to one tied to an approved campaign, rolling back means switching back to the previous number. Confirm the previous number still exists and is not retired before switching.
• Throughput limit changed: If you reduced the limit to control throttling, rollback is restoring the previous limit. Do this gradually to avoid re-triggering the throttle.
• Sending paused for reputation: If you paused sending to a specific carrier, rollback means resuming that traffic. Do not resume until the recovery period has elapsed and the carrier is accepting test messages.

Before any change with rollback potential, record the prior configuration so it can be restored. This applies to platform settings, environment variables, and deployed workflow definitions.

Edge cases

• Empty failure log: If there are no failures in the 7-day window but you were told delivery is broken, the messaging is likely failing silently — messages marked as sent that never receive a delivery receipt. Investigate the gap between sent and delivery receipts rather than treating the problem as solved.
• Duplicate suppression entries: The same number may appear on the suppression list multiple times through different opt-out channels. This is harmless for blocking but can confuse analytics. Deduplicate the list for reporting, not for sending logic.
• Partial opt-in records: A consent record missing the timestamp or channel is not usable for compliance or for carrier disputes. Treat these as no opt-in rather than guessing.
• Expired consent: If the business requires periodic re-consent, a recipient with expired consent must be moved to the suppression list, not just excluded from sending, so the sending flow does not keep evaluating the number.
• Rate-limit error without a burst: If failure codes indicate throttling but volume was steady and low, the limit may be a per-number limit rather than account-wide. Check both.
• Previously registered but now rejected campaign: Campaigns can be rejected on renewal or after policy changes. Re-check the registration status periodically, not only during triage.
• Timezone mismatch: A failure window that crosses midnight may be split across two days in logs. Align timestamps to a single timezone before computing rates.
• Malformed destination numbers: Numbers without the correct country code are commonly rejected at the carrier boundary. Add a validation step that normalizes and verifies the number format before sending.

Once the five checks are in place and validated, the natural continuation is to turn the diagnostic sequence into a permanent operational control. Set up a weekly deliverability report that tracks the failure rate, complaint rate, and the pass/fail outcome of the five checks for a rolling 7-day window. That report turns this one-time triage into an ongoing monitoring loop, so delivery failures are caught before they become a compliance or reputation problem. From there, the next improvement is to review the architecture of the sending workflow with an integration specialist, because delivery failures often cluster in the same places the workflow relies on handoffs between systems.

The documented sequence in this playbook is the reference for that review.