> ## Documentation Index
> Fetch the complete documentation index at: https://help.hoopai.com/llms.txt
> Use this file to discover all available pages before exploring further.
# SMS troubleshooting — delivery failures, error codes, and carrier filtering
When SMS messages fail to deliver, the cause can range from A2P registration issues to carrier filtering to simple character encoding problems. This guide provides a systematic approach to diagnosing and resolving SMS delivery issues in the HoopAI platform.
## First steps — quick diagnostic checklist
Before diving into specific issues, check these common causes first:
| Check | Where | What to look for |
| ------------------- | --------------------------------------- | ---------------------------------------------------------- |
| A2P 10DLC status | Settings > Phone Numbers > Trust Center | Brand and campaign must both be **Active** |
| Number type | Settings > Phone Numbers | Local numbers require A2P; toll-free requires verification |
| Contact DND status | Contact record | Contact may have replied STOP |
| Account balance | Billing > Wallet | Insufficient balance blocks all sending |
| Phone number active | Settings > Phone Numbers | Number must be active and assigned |
| Message content | Conversation thread | Check for SHAFT content, blocked URLs, or excessive length |
### Quick-reference issue table
| Issue | Likely cause | Fix |
| ------------------------------- | --------------------------------- | ---------------------------------------------------------------------- |
| Messages stuck in "Pending" | A2P 10DLC registration incomplete | Complete campaign registration in Trust Center |
| Error code 30007 | Carrier filtering | Review message content for spam triggers; register your campaign |
| Contact never receives SMS | Number on Do-Not-Disturb list | Check and remove DND from contact record |
| "Message undeliverable" | Destination is a landline | Verify the number type; use voice or email instead |
| Error code 21610 | Contact replied STOP | Contact opted out — cannot message until they opt back in |
| MMS fails to send | File exceeds 5 MB | Compress or resize the attachment below 5 MB |
| Two-way SMS not working | Inbound routing misconfigured | Check webhook and inbound routing in phone number settings |
| International SMS blocked | Country not enabled | Enable destination country in Settings > Phone Numbers > International |
| Account suspended notice | Policy violation or billing issue | Contact HoopAI support |
| High failure rate on new number | Number not warmed up | Gradually increase volume over 2-4 weeks |
***
## Message status definitions
| Status | Meaning |
| --------------- | ------------------------------------------------------------ |
| **Queued** | Message accepted and waiting to be sent |
| **Sent** | Message sent to the carrier network |
| **Delivered** | Carrier confirmed delivery to the recipient's device |
| **Undelivered** | Carrier attempted delivery but failed (see error code) |
| **Failed** | Message could not be sent at all (pre-carrier rejection) |
| **Read** | Recipient opened the message (not available on all carriers) |
### "Undelivered" vs "Failed"
| | Undelivered | Failed |
| ---------------------------- | ------------------------------------------------------ | -------------------------------------------------- |
| **Where it failed** | At the carrier level | Before reaching the carrier |
| **Common causes** | Carrier filtering, invalid number, recipient opted out | A2P not registered, account issue, invalid content |
| **Has error code** | Yes (30xxx series) | Yes (various) |
| **Message left your system** | Yes | No |
***
## Error code reference
### Common delivery error codes
| Error code | Name | Cause | Fix |
| ---------- | ----------------------- | ---------------------------------------------------------------- | ----------------------------------------------------------------- |
| **30001** | Queue overflow | Too many messages queued; volume spike | Reduce sending rate; spread bulk sends over a longer window |
| **30002** | Account suspended | Account flagged or suspended for policy/billing | Contact HoopAI support to review the suspension |
| **30003** | Unreachable destination | Phone is off, out of range, or number is temporarily unavailable | Verify the phone number; retry later |
| **30004** | Message blocked | Carrier explicitly blocked the message | Check A2P registration; review message content for spam triggers |
| **30005** | Unknown destination | Phone number does not exist or is not a mobile number | Remove from contact list; landline numbers cannot receive SMS |
| **30006** | Landline or unreachable | Number is a landline or carrier cannot route to it | Verify number type; switch to voice or email for this contact |
| **30007** | Carrier violation | Message violates carrier content policies | Review content for SHAFT, URL shorteners, or spam patterns |
| **30008** | Unknown error | Carrier returned no specific reason | Retry; if persistent, contact HoopAI support with the message SID |
| **30034** | Message filtering | T-Mobile content filtering blocked the message | Review content; remove URL shorteners; ensure A2P is active |
### Registration and compliance error codes
| Error code | Name | Cause | Fix |
| ---------- | ---------------------- | -------------------------------------------------- | ---------------------------------------------------------------- |
| **21610** | STOP received | Contact opted out (replied STOP) | Cannot message this contact unless they reply START |
| **21611** | Max message queue | Exceeded queuing limit | Reduce concurrent sends |
| **21612** | Number not SMS-capable | The "From" number cannot send SMS | Use an SMS-enabled number |
| **21614** | Invalid mobile number | "To" number is not a valid mobile number | Verify and correct the phone number |
| **21408** | Permission not enabled | Account lacks SMS permissions for this destination | Enable capability in Settings > Phone Numbers or contact support |
| **63018** | Rate limit exceeded | Exceeded A2P throughput limit | Slow down sending; check trust score in Trust Center |
Error code **21610** is a compliance-enforced block. Attempting to bypass opt-outs violates TCPA regulations and carrier policies, and can result in permanent number suspension and legal liability.
### T-Mobile specific filtering
T-Mobile is the most aggressive carrier for content filtering. Common T-Mobile blocks:
| Trigger | Error | Solution |
| ---------------------------- | ----------- | --------------------------------------------------- |
| Unregistered A2P traffic | 30004/30034 | Complete A2P 10DLC registration |
| URL shortener (bit.ly, etc.) | 30034 | Use your own domain for links |
| High message volume spike | 30034 | Ramp up sending gradually |
| Content pattern match | 30034 | Vary message content; personalize with merge fields |
| Shared shortlink domains | 30034 | Use a custom tracking domain |
***
## Common delivery issues
### Messages not sending at all
Go to **Settings** > **Phone Numbers**. Confirm the sending number shows a green **Active** status. If it shows Suspended or Pending, see the number suspension section below.
Go to **Settings** > **Phone Numbers** > **Trust Center**. Both your brand and campaign must show **Active** status. If pending or rejected, messages from local numbers will be filtered or blocked.
Go to **Settings** > **Billing** and confirm your account has available balance. Messages will silently fail if your balance is zero.
Open the conversation thread and click on the failed message to see the error code. Cross-reference with the error code table above.
Ensure the phone number is valid, is a mobile number (not a landline), and includes the correct country code. US numbers should be 10 digits.
Open the contact record and check if they have a DND flag or have previously replied STOP. Error code 21610 indicates an opt-out.
### Messages marked as delivered but not received
A "Delivered" status means the carrier accepted the message — but the recipient may still not see it.
| Cause | Details |
| ---------------------- | --------------------------------------------------------------------------------------------------------------------------------------- |
| Carrier-side filtering | The carrier accepted the message but silently dropped it before final delivery. Common with unregistered campaigns or spam-like content |
| Handset issues | Recipient's phone may be off, in airplane mode, or have a full SMS inbox |
| Wrong number format | Numbers missing the country code or with extra digits may route incorrectly |
| Carrier queuing | Some carriers queue messages during congestion and deliver later; wait 15-30 minutes |
"Delivered" only confirms the carrier network accepted the message. It does **not** confirm the message reached the handset. This is a limitation of the SMS protocol, not the HoopAI platform.
### Messages going to spam on carrier networks
Even successfully delivered messages can be silently filtered:
| Cause | Fix |
| ------------------------------------- | -------------------------------------------------------- |
| URL shorteners | Replace with your own branded domain links |
| Identical messages to many recipients | Add personalization (first name, appointment date, etc.) |
| New A2P campaign (low reputation) | Start with low volume and ramp up over 1-2 weeks |
| Aggressive promotional language | Tone down marketing language; avoid ALL CAPS |
| Too many links in one message | Limit to 1 link per message |
| Free email domains in message | Do not include Gmail/Yahoo addresses in SMS content |
### Contact replied STOP but wants messages again
When a contact replies **STOP**, they are automatically added to the DND list. To resubscribe:
1. The contact can text **START**, **YES**, or **UNSTOP** to your number
2. Or you can manually remove the DND flag from their contact record under **Contact** > **DND Settings** > uncheck SMS
Only remove DND manually if the contact has explicitly requested to resubscribe through another channel (email, phone call, in person). Removing DND without consent is a TCPA violation. Document the re-opt-in request.
***
## Character limits and message segments
### GSM-7 vs Unicode encoding
SMS messages are sent in **segments**. The character limit per segment depends on the encoding:
| Encoding | Characters per segment | When used |
| ------------------- | ------------------------------------------ | --------------------------------------------- |
| **GSM-7** | 160 characters (single) / 153 (multi-part) | Standard English text, basic punctuation |
| **Unicode (UCS-2)** | 70 characters (single) / 67 (multi-part) | Emojis, non-Latin characters, special symbols |
A single emoji switches the entire message from GSM-7 to Unicode encoding, reducing your per-segment character limit from 160 to 70. A 160-character message with one emoji becomes **3 segments** instead of 1, tripling your cost.
### Characters that trigger Unicode encoding
| Character type | Examples | Impact |
| -------------------- | --------------------------- | ------------------------------------------------- |
| Emojis | Any emoji | Switches to Unicode |
| Smart quotes | " " ' ' | Switches to Unicode — use straight quotes instead |
| Long dashes | — (em dash) | Switches to Unicode — use hyphen instead |
| Non-Latin scripts | Chinese, Arabic, Cyrillic | Switches to Unicode |
| Some special symbols | Certain accented characters | Depends on specific character |
### How segments are counted
| Message length (GSM-7) | Segments | Cost multiplier |
| ---------------------- | -------- | --------------- |
| 1-160 characters | 1 | 1x |
| 161-306 characters | 2 | 2x |
| 307-459 characters | 3 | 3x |
| 460-612 characters | 4 | 4x |
| Message length (Unicode) | Segments | Cost multiplier |
| ------------------------ | -------- | --------------- |
| 1-70 characters | 1 | 1x |
| 71-134 characters | 2 | 2x |
| 135-201 characters | 3 | 3x |
| 202-268 characters | 4 | 4x |
To check how many segments your message will use before sending, use a tool like [twiliodevsupport.github.io/sms-counter](https://twiliodevsupport.github.io/sms-counter/) to count characters and segments.
***
## MMS file limits and supported formats
| Format | Supported | Max file size |
| --------------------- | ----------------------- | ------------------------------- |
| JPEG (.jpg, .jpeg) | Yes | 5 MB |
| PNG (.png) | Yes | 5 MB |
| GIF (.gif) | Yes | 5 MB (under 500 KB recommended) |
| MP4 (.mp4) | Yes | 5 MB (under 1 MB recommended) |
| VCF (.vcf) | Yes | 5 MB |
| PDF (.pdf) | Limited carrier support | 5 MB |
| HEIC, WEBP, TIFF, AVI | Not supported | N/A |
Large MMS files (over 1 MB) may fail to deliver on some carrier networks or may be heavily compressed. Keep images under 500 KB and videos under 1 MB for best results.
For large files or unsupported formats, upload the file to a hosting service and include a link in your SMS instead of attaching directly.
***
## Delivery receipts and read receipts
| Feature | Availability |
| ------------------------------- | ---------------------------------------------------------------------------- |
| **Delivery receipt** (DLR) | Available for most US carriers; confirms message reached the carrier network |
| **Read receipt** | Not available for standard SMS; only available with RCS (limited support) |
| **Delivery status in platform** | Shown in the conversation timeline as Delivered, Undelivered, or Failed |
### DLR limitations
* Delivery receipts confirm the message reached the **carrier network**, not necessarily the recipient's device
* Some carriers do not return delivery receipts (message shows as "Sent" indefinitely)
* Pre-paid phone plans may not support DLR
* International messages have less reliable DLR
***
## Number suspended or flagged
### What triggers suspension
* Multiple spam complaints from recipients
* Sending to a high percentage of invalid numbers
* Violating carrier content policies (SHAFT content, debt collection without consent, etc.)
* Failing to honor opt-out requests
* Billing delinquency
### Number status indicators
| Status | Meaning |
| ------------- | -------------------------------------------------- |
| **Active** | Number is fully operational |
| **Pending** | Registration or provisioning in progress |
| **Suspended** | Number has been suspended — cannot send or receive |
| **Flagged** | Number is under review and may be suspended soon |
### How to request reinstatement
Check your email and the Trust Center for a suspension notice that details the reason.
If content-related, revise your messaging templates. If opt-out related, audit your DND and unsubscribe processes.
Contact HoopAI support with your number, the suspension reason, and a description of the corrective steps you have taken.
Reinstatement is not guaranteed. If the violation is severe or repeated, you may need to provision a new number and re-register your campaign.
***
## International SMS issues
| Issue | Cause | Fix |
| ---------------------- | ------------------------------------------------ | -------------------------------------------------------------- |
| Message not delivered | International sending not enabled | Enable in Settings > Phone Numbers > International Permissions |
| High cost per message | International rates vary by country | Check rate card before sending |
| Number format rejected | Missing country code | Use E.164 format: +\[country code]\[number] (e.g., +44 for UK) |
| Content blocked | Different countries have different content rules | Research destination country regulations |
| Sender ID mismatch | Some countries require pre-registered sender IDs | Register sender ID with destination country carrier |
### Sender ID requirements by region
| Region | Sender ID required | Notes |
| ------------------- | ------------------ | ---------------------------------------- |
| United States | No | 10DLC or toll-free number used as sender |
| Canada | No | Local number used as sender |
| United Kingdom | Yes | Must register alphanumeric Sender ID |
| Australia | Yes | Pre-registered Sender ID required |
| India | Yes | DLT registration and entity ID required |
| EU (most countries) | Yes | Varies by country |
International SMS is significantly more expensive than domestic US messaging and has varying deliverability depending on the destination country. For high-volume international messaging, consider using a provider specializing in that region.
***
## Two-way SMS not working
If you can send messages but are not receiving inbound replies:
Go to **Settings** > **Phone Numbers** and confirm the number has **SMS** and **Inbound SMS** capabilities enabled. Some numbers are provisioned as outbound-only.
In the phone number settings, verify that inbound messages are routed to the correct account. Misconfigured routing sends replies into a black hole.
If you are using a custom webhook for inbound messages, confirm the webhook URL is correct, reachable, and returning a 200 status code.
Inbound messages appear in the **Conversations** tab. If no user is assigned, it may not trigger notifications. Check your auto-assignment rules.
Send an inbound test from a phone on a different carrier. Some carrier-to-carrier routes have intermittent issues.
***
## Message queuing and delays
Messages may experience delays due to:
| Cause | Typical delay | Resolution |
| --------------------- | ------------------ | ---------------------------------------------------- |
| A2P throughput limits | Seconds to minutes | Upgrade trust score or spread sends over time |
| Carrier congestion | Seconds | Automatic retry; no action needed |
| Quiet hours queuing | Hours | Messages queued until sending window opens |
| Large campaign sends | Minutes to hours | Platform throttles to comply with A2P limits |
| System maintenance | Minutes | Rare; messages are queued and sent after maintenance |
***
## How to test SMS delivery
Send a test message from the platform to your personal phone. Verify delivery and content.
If possible, test delivery to phones on different carriers (AT\&T, T-Mobile, Verizon). Carrier filtering varies.
Send a message containing a link to verify it is not filtered. Use your own domain, not a URL shortener.
Send an MMS with an image to verify media delivery and quality.
Reply STOP from your test phone to confirm DND is applied. Reply START to confirm resubscription works.
***
## Escalating delivery issues to support
If you have exhausted the troubleshooting steps above, contact HoopAI support with the following information:
| Information needed | Where to find it |
| --------------------------- | ------------------------------------------------- |
| account name and ID | Settings > Business Profile |
| Phone number (From) | Settings > Phone Numbers |
| Recipient phone number (To) | Contact record |
| Error code | Conversation thread > click failed message |
| Message content | Conversation thread |
| Date and time of failure | Conversation thread |
| A2P registration status | Settings > Trust Center |
| Frequency of issue | Every message, intermittent, or carrier-specific? |
***
## Frequently asked questions
Some carriers do not return delivery receipts, so the status remains at "Sent." This does not necessarily mean the message was not delivered — it means the carrier did not confirm delivery. This is common with some pre-paid carriers and MVNOs (smaller carriers). If the recipient confirms they received it, the message was delivered successfully.
SMS messages longer than 160 characters (GSM-7) or 70 characters (Unicode) are split into multiple segments, each billed separately. Emojis switch the encoding to Unicode, which reduces the character limit per segment. See the character limits section above.
No. Landline numbers cannot receive SMS or MMS. If you attempt to send to a landline, you will receive error code 30005 or 30006. Verify that your contact list contains mobile numbers only.
T-Mobile has the most aggressive content filtering. Common triggers include: unregistered A2P traffic, URL shorteners (bit.ly), identical messages sent to many recipients, and sudden volume spikes. Ensure your A2P registration is active, use your own domain for links, personalize messages, and ramp up volume gradually.
If messages consistently fail to recipients on a specific carrier with error codes 30004 or 30034, your number may be blocked by that carrier. Test by sending to numbers on different carriers. If only one carrier fails, the number is likely blocked on that network.
Error **30003** means the destination is unreachable (phone is off, out of service area, or temporarily unavailable). Error **30005** means the number does not exist or is not capable of receiving SMS (e.g., a disconnected number or landline). 30003 may resolve if you try again later; 30005 is permanent.
Technically, messages may still be transmitted, but carriers (especially T-Mobile) will heavily filter or block unregistered A2P traffic. Your messages will have very low deliverability. A2P registration is effectively required for reliable SMS delivery from local numbers.
Your message likely contained an emoji or special character that switched the encoding from GSM-7 to Unicode. This reduces the per-segment character limit from 160 to 70, causing a 160-character message to become 3 segments. Remove emojis and special characters to reduce segment count.
Messages are typically queued for up to 4 hours. If the message cannot be delivered within that window (e.g., recipient's phone is off for an extended period), it will be marked as undelivered. Messages queued due to quiet hours will be sent when the sending window opens.
No. Once an SMS is sent, it cannot be recalled or deleted from the recipient's device. SMS is a fire-and-forget protocol. Always double-check message content and recipient before sending, especially for bulk campaigns.
Carriers sometimes process opt-outs from the wrong thread or due to a shared short code. Go to the contact record, check the DND settings, and manually toggle SMS back on if the contact confirms they want to receive messages. Document their re-opt-in for compliance.
If you have multiple numbers in the account, the platform may use number pool rotation. Check **Settings** > **Phone Numbers** to see which numbers are assigned to which campaigns. You can pin a specific number to a conversation or workflow.