SMS API

With the Nexmo SMS API you can send SMS from your account and lookup messages both messages that you've sent as well as messages sent to your virtual numbers. Numbers are specified in E.164 format. More SMS API documentation is at https://developer.nexmo.com/messaging/sms/overview

Download OpenAPI 3 Definition
Improve this specification

Send an SMS

Send an outbound SMS from your Nexmo account

POST https://rest.nexmo.com/sms/:format

Path Parameters

Key Description Example Default
format
Required | string

The format of the response


Must be one of: json or xml 		json json

Request body application/x-www-form-urlencoded

Key Description Example Default
api_key
Required | string

Your API key

 abcd1234 None
api_secret
string

Your API secret. Required unless sig is provided

 abcdef0123456789 None
sig
string

The hash of the request parameters in alphabetical order, a timestamp and the signature secret. See Signing Requests for more details.

 None None
from
Required | string

The name or number the message should be sent from. Alphanumeric senderID's are not supported in all countries, see Global Messaging for more details. If alphanumeric, spaces will be ignored. Numbers are specified in E.164 format.

 AcmeInc None
to
Required | string

The number that the message should be sent to. Numbers are specified in E.164 format.

 447700900000 None
text
string

The body of the message being sent. If your message contains characters that can be encoded according to the GSM Standard and Extended tables then you can set the type to text. If your message contains characters outside this range, then you will need to set the type to unicode.

 Hello World! None
ttl
integer

Advanced: The duration in milliseconds the delivery of an SMS will be attempted.

By default Nexmo attempt delivery for 72 hours, however the maximum effective value depends on the operator and is typically 24 - 48 hours. We recommend this value should be kept at its default or at least 30 minutes.


Must be between 20000 and 604800000 		900000 259200000
status-report-req
boolean

Advanced: Boolean indicating if you like to receive a Delivery Receipt.

 None true
callback
string

Advanced: The webhook endpoint the delivery receipt for this sms is sent to. This parameter overrides the webhook endpoint you set in Dashboard.

 https://example.com/sms-dlr None
message-class
integer

Advanced: The Data Coding Scheme value of the message


Must be one of: 0, 1, 2 or 3 		None None
type
string

Advanced: The format of the message body


Must be one of: text, binary, wappush, unicode, vcal or vcard 		text text
vcard
string | (vcard)

Advanced: A business card in vCard format. Depends on type parameter having the value vcard.

 None None
vcal
string | (vcal)

Advanced: A calendar event in vCal format. Depends on type parameter having the value vcal.

 None None
body
string

Advanced: Hex encoded binary data. Depends on type parameter having the value binary.

 638265253311 None
udh
string

Advanced: Your custom Hex encoded User Data Header. Depends on type parameter having the value binary.

 06050415811581 None
protocol-id
integer

Advanced: The value of the protocol identifier to use. Ensure that the value is aligned with udh.

 127 None
title
string

Advanced: The title for a wappush SMS. Depends on type parameter having the value wappush.

 Welcome None
url
string

Advanced: The URL of your website. Depends on type parameter having the value wappush.

 https://example.com None
validity
string

Advanced: The availability for an SMS in milliseconds. Depends on type parameter having the value wappush.

 300000 None
client-ref
string

Advanced: You can optionally include your own reference of up to 40 characters.

 my-personal-reference None
account-ref
string

Advanced: An optional string used to identify separate accounts using the SMS endpoint for billing purposes. To use this feature, please email support@nexmo.com

 customer1234 None

View response field descriptions

Response Fields

Field Description
message-count
string

The amount of messages in the request
messages
array of objects
Field Description
to
string

The number the message was sent to. Numbers are specified in E.164 format.
message-id
string

The ID of the message
status
string

The status of the message. See Troubleshooting Failed SMS.
remaining-balance
string

Your remaining balance
message-price
string

The cost of the message
network
string

The ID of the network of the recipient
account-ref
string

Advanced: An optional string used to identify separate accounts using the SMS endpoint for billing purposes. To use this feature, please email support@nexmo.com
Field Description 
{
  "message-count": "1",
  "messages": [
    {
      "to": "447700900000",
      "message-id": "0A0000000123ABCD1",
      "status": "0",
      "remaining-balance": "3.14159265",
      "message-price": "0.03330000",
      "network": "12345",
      "account-ref": "customer1234"
    }
  ]
}
<?xml version="1.0" encoding="UTF-8"?>
<mt-submission-response>
  <messages count="1">
    <message>
      <to>447700900000</to>
      <messageId>0A0000000123ABCD1</messageId>
      <status>0</status>
      <remainingBalance>3.14159265</remainingBalance>
      <messagePrice>0.03330000</messagePrice>
      <network>12345</network>
      <account-ref>customer1234</account-ref>
    </message>
  </messages>
</mt-submission-response>

Delivery Receipt Callback

The following are parameters sent in as a delivery receipt callback. You can subscribe to webhooks to receive notification when the delivery status of an SMS that you have sent with Nexmo changes.

POST https://example.com /webhooks/delivery-receipt

Request body application/json

Key Description Example
msisdn
string

The number the message was sent to. Numbers are specified in E.164 format.

 447700900000
to
string

The SenderID you set in from in your request.

 AcmeInc
network-code
string

The Mobile Country Code Mobile Network Code (MCCMNC) of the carrier this phone number is registered with.

 12345
messageId
string

The Nexmo ID for this message.

 0A0000001234567B
price
string

The cost of the message

 0.03330000
status
string

A code that explains where the message is in the delivery process.


Will be one of: delivered, expired, failed, rejected, accepted, buffered or unknown 		delivered
scts
string

When the DLR was received from the carrier in the following format YYMMDDHHMM. For example, 2001011400 is at 2020-01-01 14:00

 2001011400
err-code
string

The status of the request. Will be a non 0 value if there has been an error, or if the status is unknown. See the Delivery Receipt documentation for more details

 0
api-key
string

The API key that sent the SMS. This is useful when multiple accounts are sending webhooks to the same endpoint.

 abcd1234
message-timestamp
string

The time when Nexmo started to push this Delivery Receipt to your webhook endpoint.

 2020-01-01 12:00:00 +0000
timestamp
string

A timestamp in Unix (seconds since the epoch) format. Only included if you have signatures enabled

 1582650446
nonce
string

A random string to be used when calculating the signature. Only included if you have signatures enabled

 ec11dd3e-1e7f-4db5-9467-82b02cd223b9
sig
string

The signature to enable verification of the source of this webhook. Please see the developer documentation for validating signatures for more information, or use one of our published SDKs. Only included if you have signatures enabled

 1A20E4E2069B609FDA6CECA9DE18D5CAFE99720DDB628BD6BE8B19942A336E1C
Request model
{
  "msisdn": "447700900000",
  "to": "AcmeInc",
  "network-code": "12345",
  "messageId": "0A0000001234567B",
  "price": "0.03330000",
  "status": "delivered",
  "scts": "2001011400",
  "err-code": "0",
  "api-key": "abcd1234",
  "message-timestamp": "2020-01-01T12:00:00.000+00:00",
  "timestamp": 1582650446,
  "nonce": "ec11dd3e-1e7f-4db5-9467-82b02cd223b9",
  "sig": "1A20E4E2069B609FDA6CECA9DE18D5CAFE99720DDB628BD6BE8B19942A336E1C"
}

Inbound SMS Webhook

If you rent one or more virtual numbers from Nexmo, inbound messages to that number are sent to your webhook endpoint.

When you receive an inbound message, you must send a 2xx response. If you do not send a 2xx response Nexmo will resend the inbound message for the next 24 hours.

POST https://example.com /webhooks/inbound-sms

Request body application/json

Key Description Example
api-key
Required | string

The Nexmo API Key of the receiving account.

 abcd1234
msisdn
Required | string

The phone number that this inbound message was sent from. Numbers are specified in E.164 format.

 447700900001
to
Required | string

The phone number the message was sent to. This is your virtual number. Numbers are specified in E.164 format.

 447700900000
messageId
Required | string

The ID of the message

 0A0000000123ABCD1
text
Required | string

The message body for this inbound message.

 Hello world
type
Required | string

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.
 text
keyword
Required | string

The first word in the message body. Converted to upper case.

 HELLO
message-timestamp
Required | string

The time when Nexmo started to push this Delivery Receipt to your webhook endpoint.

 2020-01-01 12:00:00 +0000
timestamp
string

A unix timestamp representation of message-timestamp.

 1578787200
nonce
string

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.

 aaaaaaaa-bbbb-cccc-dddd-0123456789ab
concat
string

True - if this is a concatenated message. This field does not exist if it is a single message

 true
concat-ref
string

The transaction reference. All parts of this message share this value.

 1
concat-total
string

The number of parts in this concatenated message.

 3
concat-part
string

The number of this part in the message. Counting starts at 1.

 2
data
string | (binary)

The content of this message, if type is binary.

 None
udh
string

The hex encoded User Data Header, if type is binary

 None
Request model
{
  "api-key": "abcd1234",
  "msisdn": "447700900001",
  "to": "447700900000",
  "messageId": "0A0000000123ABCD1",
  "text": "Hello world",
  "type": "text",
  "keyword": "HELLO",
  "message-timestamp": "2020-01-01T12:00:00.000+00:00",
  "timestamp": "1578787200",
  "nonce": "aaaaaaaa-bbbb-cccc-dddd-0123456789ab",
  "concat": "true",
  "concat-ref": "1",
  "concat-total": "3",
  "concat-part": "2",
  "data": "abc123",
  "udh": "abc123"
}

Errors

Nexmo uses error codes to report back when an issue was encountered. Below you can find a full table to error codes:

Code Text Meaning
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
Example response
{
  "message-count": "1",
  "messages": [
    {
      "status": "2",
      "error-text": "Missing to param"
    }
  ]
}