SMS API Reference

Send an SMS

• Request - send an SMS to a user.
• Response - ensure that your request to the SMS API was successful.
• Delivery Receipt - check that the user received your message.
• Inbound messages - handle inbound messages from the user.

Request

An SMS API request looks like:

curl -X "POST" "https://rest.nexmo.com/sms/json" \
  -d "from=Nexmo" \
  -d "text=A text message sent using the Nexmo SMS API" \
  -d "to=TO_NUMBER" \
  -d "api_key=API_KEY" \
  -d "api_secret=API_SECRET"

This request contains:

• Base URL
• Parameters
• Authentication information
• Security
• Encoding

Base URL

All requests to the SMS API must contain https://rest.nexmo.com/sms followed by either /json or /xml depending on the response content type. Your base URL becomes either:

JSON

https://rest.nexmo.com/sms/json

or XML

https://rest.nexmo.com/sms/xml

Parameters

The following table shows the parameters you use in the request:

Authentication information

If you are not using applications, you use the following parameters for calls to Nexmo API:

Note: You find your Key and Secret in Dashboard.

If you are using signatures to verify your requests use:

Security

To ensure privacy, you must use HTTPS for all Nexmo API requests.

Encoding

You submit all requests with a POST or GET call using UTF-8 encoding and URL encoded values. The expected Content-Type for POST is application/x-www-form-urlencoded. For calls to a JSON endpoint, we also support:

• application/json
• application/jsonrequest
• application/x-javascript
• text/json
• text/javascript
• text/x-javascript
• text/x-json when posting parameters as a JSON object.

If you are using GET, you must set Content-Length  in the request header.

Response

Each request you make using the SMS API returns a:

Response - the status and price of your request to Nexmo in JSON or XML format. Delivery receipt - the status and cost of the SMS sent by Nexmo to your user.

Note: you are only charged for correctly submitted outbound SMS. If status is not 0, you are not charged.

The response is send in the api.txt file when you make a request from the browser.

Each response comes:

• In a specific Format
• With Keys and values

Format

You set the response type using the Base URL. The following table shows example responses in JSON or XML:

{
  "message-count":"1",
  "messages":[
    {
    "status":"returnCode",
    "message-id":"messageId",
    "to":"to",
    "client-ref":"client-ref",
    "remaining-balance":"remaining-balance",
    "message-price":"message-price",
    "network":"network",
    "error-text":"error-message"
    }
  ]
}

<?xml version='1.0' encoding='UTF-8' ?>
<mt-submission-response>
  <messages count='x'>
   <message>
    <messageId>${messageId}</messageId>
    <to>${to}</to>
    <clientRef>${client-ref}</clientRef>
    <status>${returnCode}</status>
    <errorText>${error-message}</errorText>
    <remainingBalance>${account-balance}</remainingBalance>
    <messagePrice>${message-price}</messagePrice>
    <network>${network}</network>
   </message>
  </messages>
</mt-submission-response>

Keys and Values

The response contains the following keys and values:

Error codes

The following response codes are for 2FA and Campaign Subscription Management only.

The following response codes are for 2FA only.

The following response codes are for Campaign Subscription Management only.

Examples

This section gives examples of:

Successful responses

{
  "message-count":"1",
  "messages":[
    {
    "status":"0",
    "message-id":"00000123",
    "to":"44123456789",
    "remaining-balance":"1.10",
    "message-price":"0.05",
    "network":"23410"
    }
  ]
}

<?xml version='1.0' encoding='UTF-8' ?>
<mt-submission-response>
  <messages count='1'>
   <message>
    <messageId>00000123</messageId>
    <to>44123456789</to>
    <messagePrice>0.05</messagePrice>
    <remainingBalance>1.15</remainingBalance>
    <network>23410</network>
    <status>0</status>
   </message>
  </messages>
</mt-submission-response>

Successful response, sent in three parts

{
  "message-count":"3",
  "messages":[
    {
    "status":"0",
    "message-id":"00000124",
    "to":"44123456789",
    "remaining-balance":"1.10",
    "message-price":"0.05",
    "network":"23410"
    },
    {
    "status":"0",
    "message-id":"00000125",
    "to":"44123456789",
    "remaining-balance":"1.05",
    "message-price":"0.05",
    "network":"23410"
    },
    {
    "status":"0",
    "message-id":"00000126",
    "to":"44123456789",
    "remaining-balance":"1.00",
    "message-price":"0.05",
    "network":"23410"
    }
  ]
}

<?xml version='1.0' encoding='UTF-8' ?>
<mt-submission-response>
  <messages count='3'>
   <message>
    <messageId>00000124</messageId>
    <to>44123456789</to>
    <messagePrice>0.05</messagePrice>
    <remainingBalance>1.15</remainingBalance>
    <network>23410</network>
    <status>0</status>
   </message>
   <message>
    <messageId>00000125</messageId>
    <to>44123456789</to>
    <messagePrice>0.05</messagePrice>
    <remainingBalance>1.10</remainingBalance>
    <network>23410</network>
    <status>0</status>
   </message>
   <message>
    <messageId>00000126</messageId>
    <to>44123456789</to>
    <messagePrice>0.05</messagePrice>
    <remainingBalance>1.10</remainingBalance>
    <network>23410</network>
    <status>0</status>
   </message>
  </messages>
</mt-submission-response>

Error responses

{
  "message-count":"1",
  "messages":[
    {
    "status":"2",
    "error-text":"Missing from param"
    }
  ]
}

<?xml version='1.0' encoding='UTF-8' ?>
<mt-submission-response>
  <messages count='1'>
   <message>
    <status>2</status>
    <errorText>Missing from param</errorText>
   </message>
  </messages>
</mt-submission-response>

Delivery Receipt

Each request you make using the Nexmo API returns a:

• Response - the status and cost of your request to Nexmo in JSON or XML format.
• Delivery Receipt - if you have set a webhook endpoint, Nexmo forwards this delivery receipt to it. Carriers return a Delivery Receipt (DLR) to Nexmo to explain the delivery status of your message. If the message is not received, the delivery receipt explains why your message failed to arrive.

The Delivery Receipt is sent using a GET HTTP request to your webhook endpoint. When you receive the DLR, you must send a 200 OK response. If you do not send the 200 OK, Nexmo resends the delivery receipt for the next 72 hours.

When you implement your response, ensure that your logic is not case-sensitive for the response codes.

A Delivery Receipt has a:

• Format
• Keys and Values

Format

The following code shows an example of a Delivery Receipt:

?msisdn=66837000111&to=12150000025&network-code=52099&messageId=000000FFFB0356D2&price=0.02000000&status=delivered&scts=1208121359&err-code=0&message-timestamp=\2020-01-01\+12%3A00%3A00

{
  "msisdn": "447700900000",
  "to": "447700900001",
  "network-code": "52099",
  "messageId": "02000000E68951D8",
  "price": "0.02000000",
  "status": "delivered",
  "scts": "1208121359",
  "err-code": "0",
  "message-timestamp": "2020-01-01 12:00:00"
}

Keys and Values

The Nexmo Delivery Receipt includes:

Inbound messages

If you rent one or more virtual numbers from Nexmo, inbound messages to that number are sent to your webhook endpoint. inbound messages comply to the SMS format, if a message sent to your virtual number is longer than maximum number of characters, concat is true and you receive the message in parts. Use the concat-ref, concat-total and concat-part parameters to reassemble the parts into the message.

Inbound messages are sent using a GET or POST HTTP request to your webhook endpoint. When you receive an inbound message, you must send a 200 OK response. If you do not send the 200 OK, Nexmo resends the inbound message for the next 24 hours.

Keys and Values

The inbound message includes:

For an inbound message

For concatenated inbound messages

For binary messages