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 |
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
Verify the phone number is active
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.
Check A2P registration status
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.
Check SMS credits / account balance
Go to Settings > Billing and confirm your account has available balance. Messages will silently fail if your balance is zero.
Check the error code
Open the conversation thread and click on the failed message to see the error code. Cross-reference with the error code table above.
Verify the recipient's number
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.
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:- The contact can text START, YES, or UNSTOP to your number
- Or you can manually remove the DND flag from their contact record under Contact > DND Settings > uncheck SMS
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 |
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 |
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
Identify the violation
Check your email and the Trust Center for a suspension notice that details the reason.
Fix the root cause
If content-related, revise your messaging templates. If opt-out related, audit your DND and unsubscribe processes.
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:Verify number capabilities
Go to Settings > Phone Numbers and confirm the number has SMS and Inbound SMS capabilities enabled. Some numbers are provisioned as outbound-only.
Check inbound message routing
In the phone number settings, verify that inbound messages are routed to the correct sub-account. Misconfigured routing sends replies into a black hole.
Review webhook configuration
If you are using a custom webhook for inbound messages, confirm the webhook URL is correct, reachable, and returning a 200 status code.
Check for conversation assignment
Inbound messages appear in the Conversations tab. If no user is assigned, it may not trigger notifications. Check your auto-assignment rules.
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 to your own phone
Send a test message from the platform to your personal phone. Verify delivery and content.
Test across carriers
If possible, test delivery to phones on different carriers (AT&T, T-Mobile, Verizon). Carrier filtering varies.
Test with links
Send a message containing a link to verify it is not filtered. Use your own domain, not a URL shortener.
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 |
|---|---|
| Sub-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
Why do my messages show 'Sent' but never 'Delivered'?
Why do my messages show 'Sent' but never 'Delivered'?
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.
Why am I being charged for multiple segments?
Why am I being charged for multiple segments?
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.
Can I send SMS to landline numbers?
Can I send SMS to landline numbers?
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.
Why are my messages being filtered by T-Mobile?
Why are my messages being filtered by T-Mobile?
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.
How do I know if my number is blocked?
How do I know if my number is blocked?
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.
What is the difference between error 30003 and 30005?
What is the difference between error 30003 and 30005?
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.
Can I send SMS without A2P 10DLC registration?
Can I send SMS without A2P 10DLC registration?
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.
Why did my message cost 3x what I expected?
Why did my message cost 3x what I expected?
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.
How long are messages queued before they expire?
How long are messages queued before they expire?
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.
Can I recall or delete a sent message?
Can I recall or delete a sent message?
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.
A contact says they did not reply STOP, but they are blocked. What do I do?
A contact says they did not reply STOP, but they are blocked. What do I do?
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.
Why are my messages being sent from a different number than expected?
Why are my messages being sent from a different number than expected?
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.