Sending SMS with Delivery Receipts


The Atmosphere® Messaging API makes it easy to send and receive SMS messages through your IntelePeer DID or Toll-Free phone numbers. Short Codes and Alphanumeric Codes are also available. Send-only for SMS messages through Alphanumeric Codes. In this document, you’ll find instructions on how to configure your numbers to send SMS messages with delivery receipts.

Sending a single SMS message

You can send an SMS message with a single call to the Atmosphere® Messaging API. Please ensure you are following IntelePeer API conventions.






This API method requires an Authorization Token. Learn more about the Authorization token in Atmosphere® API Authentication.



Data Type







Properly formatted customer inventory code (long code, shortcode, alphanumeric sender id) (e.g., 1-12345, 57-Hello8, +13031112222) see: Code Formatting





E.164-formatted number to which the message is being sent to (e.g., +13038675309)





The message to be sent





Set to true enable delivery receipt on this request (default=false)





May be optionally supplied when “dlr” is set to true to set additional DLR options beyond the standard behavior







If set to true, the system will generate an additional intermediary DLR which indicates when the MT message is successfully enqueued into the SMS network. This DLR will reflect the state “ACCEPTD” when received.


This DLR represents a positive-confirmation DLR and not negative-confirmation. As such, if requested, the lack of receipt of this DLR is an indication of failure to enqueue the message to the SMS network.


This is primarily used when final delivery status through the carrier/handset is unavailable in the destination country.





An identifier to be appended to the message in the Message Detail Record for correlation with other system records.


Request example for Long codes

The “to” parameter for sending from Long Codes must be in E.164 format.


"from": "+12191112222",
"to": "+13038675309",
"text": "Hello World!",
"dlr": true,
"guid": "1123123123123123"

"from": "+13032225555",
"to": "+172034448888",
"text": "Hello World",
"dlr": true,
"dlroptions": {
"include_accepted": true
"guid": "1122334455667788"

Sending an SMS message with delivery receipts

A Delivery Receipt (DLR) provides you the details of success or failure of your outbound SMS messages.  There are three phases at which progress can be confirmed:


  • API Acknowledgement – IntelePeer will send an acknowledgment to the API call to our systems. A 202 message means the message is progressing and more details on response codes can be found at:
  •  Checking Message Status – Once the IntelePeer Servers have sent a message downstream the Message Detail Records [MDR] is updated with a further status which can be found at
  • Optional Carrier Acknowledgement / Confirmation – IntelePeer provides an optional parameter on an outbound message to receive a Delivery Receipt [DLR] from the Mobile Provider to which the message is sent and more details can be found on this page.


Delivery Receipt Types


  • Carrier Acknowledgment: The outbound message has reached the carrier SMSC successfully and it is being processed for delivery to the end-user for A2P. For mobile providers in many countries confirmation that the message has reached the SMSC is all that is available.
  • Carrier Confirmation – The carrier has sent the outbound message to the end-user’s mobile device.


The Message State sent for Carrier Acknowledgement and Carrier Confirmation are the same. Your IntelePeer Solutions Engineer can tell you what is available for specific providers in a country.


Delivery Receipt Message States


Message StateStatusDescription




DELIVRDMessage is delivered to




EXPIREDMessage validity period has



DELETEDMessage has been deleted



UNDELIVMessage is undeliverable







ACCEPTDMessage is in accepted state (i.e. has been manually read on behalf of the subscriber by customer service)



UNKNOWNMessage is in invalid state
REJECTEDREJECTDMessage is in a rejected state


Delivery Receipt Message States are provided to IntelePeer by mobile carriers and we pass them to our customers unaltered. There are a few items to consider when looking at a DLR:


  • Not all carriers return DLRs
  • Some carriers who do return DLRs may not always do so reliably. Carriers across the globe have been known to change this offering without notice, therefore the lack of a DLR may not indicate an issue with the system.
  • As noted above, in some cases a DLR represents the delivery of a message to the SMSC [Carrier Acknowledgement] and in others the delivery of a message to the Handset [Carrier Confirmation].
  • Carriers will send the DLR back prior to applying SPAM filters. This is done to prevent spammers from trying to circumvent the Carriers SPAM Filter algorithms.


Setting Up Your System to Receive DLRs

SMS DLRs are delivered in the same way that an inbound message is delivered – to a customer dedicated webhook.


There are three steps to set up and test delivery receipts, after SMS has been set up on an account and (at least) one number has been SMS provisioned.


The format for DLRs are application/json to and they are sent to your DLR webhook in the following format:


When sending an SMS, the message may be split into multiple segments in transit. If the final carrier supports DLRs, you should expect to receive a DLR webhook POST for each segment. The number of segments your message is split into is returned in the original send request.


Task 1: Set up your webserver to receive DLR webhooks

Just like your inbound SMS webserver, it should support receiving HTTP POST messages on an endpoint with an expected content type of application/json.


Task 2: Configure Your Account’s DLR webhook.

Unlike inbound SMS messages, where each code can have a unique webhook for delivery, all DLRs are delivered to the same webhook. To set up this webhook, provide the URL through the existing “account configuration” endpoint, but provide a “dlrwebhook” parameter to your JSON request. 


Example DLR

"content": "DLR",
"from": "+18001112222",
"to": "+12223334444",
"refid": "SM5C59B99900012345671000F9170FDB",
"status": "DELIVRD",
"message_state": "DELIVERED"

Field NameDescription



“Always DLR”




The sending code



The receiving SMS-enabled handset




The reference identifier for the message, which was passed back in the original send request





The final status of the message. Values per SMPP Protocol Specification v3.4, Table B-2


message_stateShould be present for SMSC Delivery Receipts and Intermediate Notifications. Will be set to null when not available.

Values per SMPP Protocol Specification v3.4, 5.2.28


Sample Code (Python 2.7+):


import requests

url = ""

payload = {

"dlrwebhook": ""


headers = {

"Authorization": "Bearer INSERT_API_TOKEN_HERE",

"Content-Type": "application/json",

"cache-control": "no-cache"


response =, json=payload, headers=headers)



This same endpoint is also used to set up your account secret which can be provided in the same request under the parameter, “secret”.


Task 3: Send an SMS message using the API (with DLR enabled in the request).


Task 4: Validate Delivery Receipts are being delivered to your webhook.

Upon sending an SMS message, and receiving it on a cellphone, you should expect to see your webhook receive one request per segment which that SMS was split into.