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 Expose the error
0 Message Delivered to Carrier Message delivered to carrier Yes
187 Spam Detected – Statistical Statistical spam detected Yes
188 Spam Detected -Keyword Keyword spam detected Yes
189 Spam Detected Spam detected Yes
482 Loop Detected Loop detected Yes
600 Destination Carrier Queue Full Destination carrier could not accept messages Yes
610 submit_sm or submit_multi failed Message submission failed Yes
620 Destination App Error Destination application error Yes
630 NACK Message not acknowledge Yes
700 Invalid Service Type Invalid service type No
720 Invalid Destination Address Invalid destination number Yes
740 Invalid Source Address Invalid source number Yes
999 Unknown Error Unknown error Yes

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 ""