Track your SMS delivery

When you click Send, you expect your message to get delivered. But here’s the reality, sometimes a recipient never receives your SMS 😢 Perhaps the recipient mistyped their phone number, your queue overflowed, your account is out of funds, carriers are blocking your content, etc. These things happen on occasion.

To help you understand when this has happened and how to fix it, Ytel provides you with an SMS “Status” and a “Delivery Status”. If your message doesn’t get delivered, then you’ll also receive an error code.

Status
Status is a way of letting you know if Ytel has been able to successfully receive your request and send it to the carrier. While most messages start off as “Queued”, they will eventually end up as “Success” or “Failed”. Here’s a little information about each of these statuses:

Status

Description

Queued

Ytel has received your request to send the message.

Success

Ytel has successfully sent your message to the upstream carrier.

Failed

Ytel couldn't receive your request or send it to the upstream carrier. Ytel often provides an error code to help you identify the reason.

Delivery Status
On the other hand, Delivery Status is used to help you understand whether the upstream carrier was able to deliver your message. Receiving a delivery status is predicated upon:

  • Requesting it by setting DeliveryStatus to True when you make your send SMS request.
  • Ytel receiving a delivery receipt from the carrier.

Whenever Ytel sends an SMS to a carrier, the carrier may return a delivery receipt stating whether the SMS was delivered or not. Because carriers don’t always send a delivery receipt, and sometimes merely send an acknowledgment of reception to their inherent network, Ytel cannot be 100% certain that a carrier delivery receipt stating that the SMS was received means that it actually reached your recipient.

When a Delivery Status is requested, the Delivery Status is initially set to “Sent” to indicate that you have made such a request. When and if Ytel receives a delivery receipt from the carrier, then the status will get updated to either Received or Undelivered. Here's more information regarding each of these delivery statuses:

Delivery Status

Description

Sent

Ytel has received your request to provide a delivery status of undelivered or delivered upon successfully receiving a delivery receipt from the upstream carrier.

Received

Ytel has received a delivery receipt from the upstream carrier indicating that the message was delivered.

Undelivered

Ytel has received a delivery receipt indicating that the message was not delivered. Ytel will provide an error code to help you identify the reason.

Remember, if you want to receive a delivery status then you must set DeliveryStatus to true with your send SMS request. See the DeliveryStatus parameter associated with the Send SMS endpoint https://docs.ytel.com/reference/sms#sendsms for more info.

In the event that your message is “Undelivered”, you’ll also receive one of the following error codes:

Error Code

Description

2000

Message blocked. Your message has been blocked from reaching the destination.

2001

Carrier violation. The carrier is filtering out your messages from being delivered.

2002

Unallocated. The destination phone number is not allocated to a mobile network.

2003

Invalid destination. The carrier is reporting the number as being unreachable.

2004

Unknown. The delivery receipt has returned a generic error message.

We also encourage you to add a MessageStatusCallback url with each send SMS request. This will allow you to get notified whenever the Status, and DeliveryStatus if requested, has been updated.


Did this page help you?