When a customer says the text didn't arrive, work through the checks in order: is the number valid and a mobile, did they opt out, was the text stopped by quiet hours, is the sending number registered, and only then, is it a carrier issue. Most cases end at one of the first three, and none of them need an engineer.

This playbook is for support teams. It gives you the order, what to ask the customer, what to hand to engineering when it gets that far, and short replies you can adapt. It only uses what Ready actually does, so where a step depends on your account, it says to check.

The ordered checks

Go top to bottom. Stop at the first one that explains it.

#CheckWhat you're looking for
1NumberTypo, missing digits, a landline or a VoIP line that can't take texts
2Opt-outThe contact replied STOP earlier, on this account
3Quiet hoursThe text was stopped by quiet hours or not sent because of the recipient's local time
4RegistrationThe sending number's carrier registration isn't approved
5FilteringA carrier filtered it as unwanted, often for content or links
6HandsetPhone off, blocked sender, full storage, wrong inbox

Check 1: the number

Ask the customer to read the number back to you, with the area code. A single wrong digit is common. Compare it to the contact record. A number Ready's own sends have already seen as a landline is refused up front on every account, with no charge, so a landline contact is a likely answer when the status is a refusal. You can see why in can you text a landline. The API route for engineers is GET /v1/validate/:phone.

Check 2: opt-out

Open the contact. If it shows opted out, that's the answer: opt-outs are refused up front and not charged. Don't re-enable a contact because the customer now says they want texts. Ask them to text START to the number themselves. Handling opt-outs explains the reasoning.

Check 3: quiet hours

Texts follow the recipient's local time, based on their area code. A campaign or automation text waits up to 24 hours for the window. A text your team types to one person in the Inbox is scheduled for when the window opens, however far off, and shows in the thread. A text sent through the API is held only if the window opens within 6 hours, otherwise it isn't sent, and your code sends it again once the window opens. A reply to someone who texted the account in the last 24 hours can go out at any hour. So "it never arrived" at 11 PM their time often means "it was never sent." Check the message status before you say it was delivered.

Check 4: registration

US business texting on local numbers needs an approved carrier registration. Unregistered traffic gets filtered. In the app, look at the registration status. If it's pending, most approvals take 2 to 7 days. See registration status lookup and fixes.

Check 5 and 6: filtering and the handset

If the first four are clean, ask what the text said. Messages with a shortened public link or an aggressive offer are the usual filter triggers; the why business texts aren't delivering post lists them. Then ask the customer to check blocked numbers and spam folders on their phone, and to try again with Wi-Fi off. A delivered status means the carrier accepted the text, not that a person read it. The delivery receipt versus read gap post explains.

What to ask the customer

  • The exact number and carrier, if they know it.
  • Roughly when they expected it, with their time zone.
  • Whether they've ever texted STOP to this number.
  • Whether other business texts reach them.
  • A screenshot of the thread, if any text did arrive.

What to escalate to engineering

Send these together, so nobody has to ask twice:

  • The recipient number in E.164, and the sending number.
  • The message ID or the time sent, with time zone.
  • The status shown in the app and the error text, verbatim.
  • What you already ruled out from checks 1 to 4.
  • Whether it's one contact or many. Many points to registration or filtering.

Reply templates

Opt-out found: "Our records show a STOP reply on this number, so we've paused texts to you. If you'd like them back, text START to the same number."

Stopped by quiet hours: "Texts are stopped outside the hours when businesses may text you, so yours wasn't sent. We'll send it again once the window opens."

Still investigating: "Thanks for the details. We've checked the number and your opt-in status and we're looking at the carrier side. We'll update you by [time]."

Wrapping up

Order is the whole trick: cheap checks first, carrier last. If your team sends through Ready, the error docs list the codes engineers will see, and you can start at /signup.

Frequently asked questions

Why does the app say delivered when the customer never saw it?

Delivered means the carrier accepted it. It says nothing about whether it was opened, or whether a filter or setting put it somewhere hidden.

Can I re-send to a contact who opted out?

No. Opted-out contacts are refused up front. The customer has to text START themselves.

Should I tell the customer to switch phones or carriers?

Not first. Rule out the number, opt-out, quiet hours and registration before you point at their handset.

When is it a registration problem?

When many contacts report the same thing, or the sending number's registration isn't approved. A single missing text is rarely registration.