Welcome to Nexmo Developer

We are improving our Documentation, API references, learning resources & tooling to help you more effectively use our services. We want to help you find everything you need to integrate Nexmo APIs into your code.

As we start this transition, we’d love to hear from you with thoughts & suggestions. If you’ve got something, positive or negative, to tell us, please tell us using the feedback tool at the bottom of each guide or file an issue on GitHub. - Nexmo

SMS API Reference

Send an SMS

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

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:

Parameter Description Required
from An alphanumeric string giving your sender address. For example, from=MyCompany20. See our information Global messaging. This is also called the SenderID. Yes.
to A single phone number in international format, that is E.164  . For example, to=447700900000. You can set one recipient only for each request. Yes.
type Default value is text. Possible values are:
  • text - for plain text SMS, you must also set the text parameter.
  • binary - for binary SMS you must also set the udh and body parameters. Do not set the text parameter.
  • wappush - a WAP Push  . You must also set the title and url parameters. Do not set the text or body parameters.
  • unicode - SMS in unicode  contain fewer characters than text. Only use unicode when your SMS must contain special characters. For more information, see Encoding.
  • vcal - send a calendar event. You send your vCal  encoded calendar event in the vcal parameter.
  • vcard - send a business card. You send your vCard  encoded business card in the the vcard parameter.
No.
text The SMS body. Messages where type is text (the default) are in UTF-8 with URL encoding. You send "Déjà vu" as a text (type=text) message as long as you encode it as D%C3%A9j%C3%A0+vu. You can see the full UTF-8 character set here  . To test if your message can be URL encoded, use: http://www.url-encode-decode.com/  . If you cannot find the character you want to send in these two references, you should use unicode. For more information, see Encoding. For text type SMS.
status-report-req Set to 1 to receive a Delivery Receipt (DLR). To receive the DLR, you have to either: No.
vcard A business card in vCard  . You must set the type parameter to vcard. No.
vcal A calendar event in vCal  . You must set the type parameter to vcal.
ttl The lifespan of this SMS in milliseconds. No
callback The webhook endpoint the delivery receipt for this sms is sent to. This parameter overrides the webhook endpoint you set in Dashboard. This must be a fully formed URL. For example: https://mysite.com/sms_api_callback.php. No
message-class Set to: 0 for Flash SMS, 1 - ME-specific, 2 - SIM / USIM specific, 3 - TE-specific See http://en.wikipedia.org/wiki/Data_Coding_Scheme  Note: Flash SMS is not fully support by all handsets and carriers. No
udh Your custom Hex encoded User Data Header (UDH)  . For example, udh=06050415811581. For binary type SMS.
protocol-id The value in decimal format for the higher level protocol  to use for this SMS. For example, to send a binary SMS to the SIM Toolkit, this would be protocol-id=127. Ensure that the value of protocol-id is aligned with udh. For binary type SMS.
body Hex encoded binary data. For example, body=0011223344556677. For binary type SMS.
title The title for a wappush SMS. For example: MyCompanyIsGreat. For wappush type SMS.
url The URL your user taps to navigate to your website. For wappush type SMS.
validity The availability period for a wappush type SMS in milliseconds. For example, validity=86400000. If you do not set this parameter, the default is 48 hours. No.

Authentication information

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

Parameter Description
api_key Your Key. For example: api_key=n3xm0rocks
api_secret Your Secret. For example: api_secret=12ab34cd

Note: You find your Key and Secret in Dashboard.

If you are using signatures to verify your requests use:

Parameter Description
api_key Your Key. For example: api_key=n3xm0rocks
sig The hash of the request parameters in alphabetical order, a timestamp and the signature secret. For example: sig=TwoMenWentToMowWentTOMowAMeadowT

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:

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

Keys and Values

The response contains the following keys and values:

Key Description
message-count The number of parts the message was split into.
messages Contains each message part.
status The processing status of the message.
message-id The ID of the SMS that was submitted (8 to 16 characters).
to The phone number your request was sent to.
client-ref The client-ref you set in your request.
remaining-balance The remaining balance in your account. The value is in EUR.
message-price The price charged for your request. The value is in EUR.
network The Mobile Country Code Mobile Network Code (MCCMNC) for the carrier of the recipient.
error-text If an error occurred, this explains what happened.

Error codes

Code Text Meaning
0 Success The message was successfully accepted for delivery by Nexmo.
1 Throttled You have exceeded the submission capacity allowed on this account. Please wait and retry.
2 Missing params Your request is incomplete and missing some mandatory parameters.
3 Invalid params The value of one or more parameters is invalid.
4 Invalid credentials The api_key / api_secret you supplied is either invalid or disabled.
5 Internal error There was an error processing your request in the Platform.
6 Invalid message The Platform was unable to process your request. For example, due to an unrecognised prefix for the phone number.
7 Number barred The number you are trying to submit to is blacklisted and may not receive messages.
8 Partner account barred The api_key you supplied is for an account that has been barred from submitting messages.
9 Partner quota exceeded Your pre-paid account does not have sufficient credit to process this message.
11 Account not enabled for REST This account is not provisioned for REST submission, you should use SMPP instead.
12 Message too long The length of udh and body was greater than 140 octets for a binary type SMS request.
13 Communication Failed Message was not submitted because there was a communication failure.
14 Invalid Signature Message was not submitted due to a verification failure in the submitted signature.
15 Illegal Sender Address - rejected Due to local regulations, the SenderID you set in from in the request was not accepted. Please check the Global messaging section.
16 Invalid TTL The value of ttl in your request was invalid.
19 Facility not allowed Your request makes use of a facility that is not enabled on your account.
20 Invalid Message class The value of message-class in your request was out of range. See https://en.wikipedia.org/wiki/Data_Coding_Scheme.
23 Bad callback :: Missing Protocol You did not include https in the URL you set in callback.
29 Non White-listed Destination The phone number you set in to is not in your pre-approved destination list. To send messages to this phone number, add it using Dashboard.
34 Invalid or Missing Msisdn Param The phone number you supplied in the to parameter of your request was either missing or invalid.

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

Code Text
101 RESPONSE_INVALID_ACCOUNT_CAMPAIGN

The following response codes are for 2FA only.

Code Text Meaning
102 RESPONSE_MSISDN_OPTED_OUT_FOR_CAMPAIGN You tried to send a message to a destination number that has opted out of your program.

The following response codes are for Campaign Subscription Management only.

Code Text
102 RESPONSE_INVALID_CAMPAIGN_SHORTCODE
103 RESPONSE_INVALID_MSISDN

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

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

Error responses

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

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

Keys and Values

The Nexmo Delivery Receipt includes:

Key Value
to The SenderID you set in from in your request.
network-code The Mobile Country Code Mobile Network Code (MCCMNC) of the carrier this phone number is registered with.
messageId The Nexmo ID for this message.
msisdn The phone number this message was sent to.
status A code that explains where the message is in the delivery process., If status is not delivered check err-code for more information. If status is accepted ignore the value of err-code. Possible values
err-code If the status is not accepted, this key will have one of the these possible values
price How much it cost to send this message.
scts The Coordinated Universal Time (UTC) when the DLR was recieved from the carrier. The scts is in the following format: YYMMDDHHMM. For example, 1101181426 is 2011 Jan 18th 14:26.
message-timestamp The time at UTC±00:00 when Nexmo started to push this Delivery Receipt to your webhook endpoint. The message-timestamp is in the following format YYYY-MM-DD HH:MM:SS. For example, 2020-01-01 12:00:00.
client-ref The client-ref you set in the request.

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:

Key Value Required
type Possible values are:
  • text - standard text.
  • unicode - URLencoded   unicode  . This is valid for standard GSM, Arabic, Chinese, double-encoded characters and so on.
  • binary - a binary message.
Yes
to The phone number the message was sent to. This is your virtual number. Yes
msisdn The phone number that this inbound message was sent from. Yes
messageId The Nexmo ID for this message. Yes
message-timestamp The time at UTC±00:00  that Nexmo started to push this inbound message to your webhook endpoint. The message-timestamp is in the following format YYYY-MM-DD HH:MM:SS. For example, 2020-01-01 12:00:00. Yes
timestamp A unix timestamp representation of message-timestamp. If your messages are signed
nonce A random string that forms part of the signed set of parameters, it adds an extra element of unpredictability into the signature for the request. You use the nonce and timestamp parameters with your shared secret to calculate and validate the signature for inbound messages. If your messages are signed

For an inbound message

Key Value Required
text The message body for this inbound message. If type is text
keyword The first word in the message body. This is typically used with short codes. If type is text

For concatenated inbound messages

Key Value Required
concat True - if this is a concatenated message. Yes
concat-ref The transaction reference. All parts of this message share this concat-ref. If concat is True
concat-total The number of parts in this concatenated message. If concat is True
concat-part The number of this part in the message. Counting starts at 1. If concat is True

For binary messages

Key Value Required
data The content of this message If type is binary
udh The hex encoded User Data Header  If type is binary

status values

Key Value
delivered this message has been delivered to the phone number.
expired the target carrier did not send a status in the 72 hours after this message was delivered to them.
failed the target carrier failed to deliver this message.
rejected the target carrier rejected this message.
accepted the target carrier has accepted to send this message.
buffered This message is in the process of being delivered.
unknown the target carrier has returned an undocumented status code.
Code Description
0 Delivered.
1 Unknown - either: An unknown error was received from the carrier who tried to send this this message. Depending on the carrier, that to is unknown. When you see this error, and status is rejected, always check if to in your request was valid.
2 Absent Subscriber Temporary - this message was not delivered because to was temporarily unavailable. For example, the handset used for to was out of coverage or switched off. This is a temporary failure, retry later for a positive result.
3 Absent Subscriber Permanent - to is no longer active, you should remove this phone number from your database.
4 Call barred by user - you should remove this phone number from your database. If the user wants to receive messages from you, they need to contact their carrier directly.
5 Portability Error - there is an issue after the user has changed carrier for to. If the user wants to receive messages from you, they need to contact their carrier directly.
6 Anti-Spam Rejection - carriers often apply restrictions that block messages following different criteria. For example, on SenderID or message content.
7 Handset Busy - the handset associated with to was not available when this message was sent. If status is Failed, this is a temporary failure; retry later for a positive result. If status is Accepted, this message has is in the retry scheme and will be resent until it expires in 24-48 hours.
8 Network Error - a network failure while sending your message. This is a temporary failure, retry later for a positive result.
9 Illegal Number - you tried to send a message to a blacklisted phone number. That is, the user has already sent a STOP opt-out message and no longer wishes to receive messages from you.
10 Invalid Message - the message could not be sent because one of the parameters in the message was incorrect. For example, incorrect type or udh.
11 Unroutable - the chosen route to send your message is not available. This is because the phone number is either currently on an unsupported network or on a pre-paid or reseller account that could not receive a message sent by from. To resolve this issue either email us at support@nexmo.com or create a helpdesk ticket at https://help.nexmo.com.
12 Destination unreachable - the message could not be delivered to the phone number.
13 Subscriber Age Restriction - the carrier blocked this message because the content is not suitable for to based on age restrictions.
14 Number Blocked by Carrier - the carrier blocked this message. This could be due to several reasons. For example, to's plan does not include SMS or the account is suspended.
15 Pre-Paid - Insufficent funds - to’s pre-paid account does not have enough credit to receive the message.
99 General Error - there is a problem with the chosen route to send your message. To resolve this issue either email us at support@nexmo.com or create a helpdesk ticket at https://help.nexmo.com.