An accepted SMS can still fail because of an invalid number, an unreachable handset or a network problem. The message record, delivery event and returned error help distinguish those outcomes from filtering.
How do I investigate a suspected filter?
You compare the message record with its SMS events. The event describes the outcome; the error and provider details help explain it.
| Event | What the event tells you |
|---|---|
sms.rejected | Processing or a downstream provider refused the accepted message. |
sms.failed | A permanent failure was reported. |
sms.undelivered | A recoverable failure was reported, such as an unreachable subscriber or network problem. |
sms.expired | The provider reported expiry. |
No event alone proves filtering. In Bird's delivery-receipt mapping, a provider reason of carrier_rejected becomes content_rejected. An unmapped reason becomes unknown, which needs investigation and may have an unrelated cause. A receipt's status determines the event separately from its reason, so a carrier rejection can accompany different failure events.
The error catalog defines blocked_by_carrier and sender_unregistered. Their absence does not rule out filtering: Bird maps carrier_rejected to content_rejected and unmapped reasons to unknown. Read the actual returned code, preserve unfamiliar values, and keep the provider details.
Which details should I save?
Keep the message ID, sender, destination, submission time, event type, normalized error.code, description and carrier_error_code. Group failures by destination, sender and message type; a single failure gives you less evidence than a change affecting a consistent group of sends.
The normalized code is the stable field for your application's handling. The description is diagnostic text, so do not parse it as a fixed contract. carrier_error_code carries the sending provider's more detailed code when supplied; it is not guaranteed to be a mobile carrier's own code. It can be empty when the provider supplies none or when a failure occurs before provider handoff.
For example, content_rejected points you toward the reported rejection, invalid_destination toward the recipient number, and provider_unavailable toward the network or capacity result. unknown leaves the cause unresolved. Share the message ID and available provider code with support when those details do not explain the failure.
Does registering my sender prevent filtering?
Registration satisfies the applicable sender programme; it does not guarantee delivery. The sender must also be eligible for the destination, and the message and traffic must meet the relevant requirements.
For US A2P messaging with local numbers, check the complete 10DLC registration: brand, campaign and number linkage. An approved brand or campaign does not by itself link every number you own. Toll-free and short-code programmes have different requirements. Other destinations may require sender-name registration.
Use SMS destinations to plan the sender choice, then confirm the applicable requirements and your workspace's registration state before launch. A country guide is a reference snapshot, not evidence that your sender is approved.
What should I do with an opt-out failure?
Preserve the preference. A send to a Bird-suppressed sender-and-recipient pair is refused at the API with E12077; that refusal creates no message or message event. A downstream report of recipient_opted_out is different: it is an outcome for an accepted message and causes Bird to record a suppression for the pair.
Supported opt-out keywords can create sender-and-recipient suppressions. Pair-level suppression events do not represent every workspace preference or every request received through customer support. Keep those broader preferences in your audience selection. Do not switch senders to evade an opt-out.
What should I check before retrying?
- Sender readiness. Confirm the sender type, registration and destination access required for this traffic.
- Permission and relevance. Confirm the person agreed to this purpose and has not withdrawn that permission.
- Content and links. Identify the business clearly, use appropriate links and review the destination's content requirements. Changing a link alone cannot establish delivery eligibility.
- Traffic and timing. Compare the failed sends with your normal pattern, queueing and the limits of the route. Repeatedly submitting the same rejected content can add cost without fixing the cause.
- The reported failure. Investigate permanent refusals before sending again. For an ambiguous API response, reuse the original idempotency key within its replay window; do not turn uncertainty into a second request automatically.
SMS routing applies destination controls before carrier handoff. An SMS integration tracks each accepted request through its message record and delivery events.
In short
A failed delivery is a starting point for investigation.
The event, normalized error and provider details describe the failure. An unknown reason does not prove carrier filtering.
Registration is one requirement, not a delivery guarantee.
Check the sender, destination, content, permission and traffic pattern before deciding what to change.
An opt-out is a preference to preserve.
Distinguish an API refusal for a suppressed pair from a downstream opt-out report, and respect the full scope of the person's request.
Keep the evidence with the message.
Save the message ID, destination, sender, time, event and error details so you can investigate a pattern or raise a useful support case.