Send SMS/MMS with Delivery Receipts

Delivery Receipts (DLR) add two new states to the messaging lifecyle – delivered and not delivered. When a message is sent, it is sent by the SMPP gateway to the SMSC with the delivery receipt value set. The SMSC will return the final disposition of the message as determined by the carrier. Values returned include the following:

Error Code SMSC Description Bandwidth API Description
0 Message Delivered to Carrier Message delivered to carrier
187 Spam Detected – Statistical Statistical spam detected
188 Spam Detected -Keyword Keyword spam detected
189 Spam Detected Spam detected
482 Loop Detected Loop detected
600 Destination Carrier Queue Full Destination carrier could not accept messages
610 submit_sm or submit_multi failed Message submission failed
620 Destination App Error Destination application error
630 NACK Message not acknowledge
650 Destination Failure Destination Failure
700 Invalid Service Type Invalid service type
720 Invalid Destination Address Invalid destination number
740 Invalid Source Address Invalid source number
750 Destination Rejected Message Destination Rejected Message
751 Destination Rejected Message too large Destination Rejected Message too large
770 Destination Rejected due to spam Destination Rejected due to spam
775 Rejected due to user opt out Rejected due to user opt out
902 Message Expired Message Expired
999 Unknown Error Unknown error

The app platform will send a new event on delivery receipt based on the value of the new messages parameter, receiptRequested. The event will initially only be delivered on failure, but will, eventually allow an event for every receipt on every message.

Messages Resource

Property Type Description Default Values
receiptRequested string (1 – 16) Controls how delivery receipt events are delivered. The default value, no, will result in no delivery receipt events being generated. The value of yes will result in delivery receipts on failure, e.g. if the message is not delivered by the stage carrier. The value of all results in an per message, when the delivery receipts is available no none,all, error
State Remains unchanged
Delivery State Delivered/Not-Delivered
Delivery Code
Delivery Description

Example: Send SMS with delivery receipt

curl -v -X POST{userId}/ \
  -u {token}:{secret} \
  -H "Content-type: application/json" \
    -d \
    "to": "+18284467788",
    "from": "+19197124466",
    "text": "Watch out for the construction on I-25 and Hwy 52",
    "receiptRequested" : "all",
    "callbackUrl" : ""

var Bandwidth = require("node-bandwidth");

var client = new Bandwidth({
    userId    : "YOUR_USER_ID",
    apiToken  : "YOUR_API_TOKEN",
    apiSecret : "YOUR_API_SECRET"
var message = {
  from: "+19195551212",  // <-- This must be a Bandwidth number on your account
  to: "+191955512142",
  text: "Hello World",
  receiptRequested: "all",
  callbackUrl: "",

//Use Promises
.then(function(message) {
    console.log("Message sent with ID " +;
.catch(function(err) {
using System;
using System.Threading.Tasks;
using Bandwidth.Net;
using Bandwidth.Net.Api;

public class Program
  //API credentials which can be found on your account page at
  private const string UserId = "u-userID"; //{user_id}
  private const string Token = "t-token"; //{token}
  private const string Secret = "secret"; //{secret}

  public static void Main()
    catch (Exception ex)
      Environment.ExitCode = 1;

  private static async Task RunAsync()
    var client = new Client(UserId, Token, Secret);

    await client.Message.SendAsync(new MessageData
      From = "+19195551212",
      To = "+191955512142",
      Text = "Test",
      ReceiptRequested = MessageReceiptRequested.All,
      CallbackUrl = ""


Callback events will be sent on each state transition.

POST /your_url HTTP/1.1
Content-Type: application/json; charset=utf-8
User-Agent: BandwidthAPI/v1

  "messageId": "m-kv54fk7x66fakdnb5owdk4y",
  "messageUri": "https://api.../<userId>/messages/m-absd",
  "errorcode": "720",
  "error":"Invalid Service Type"

results matching ""

    No results matching ""