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.

Download OpenAPI 3 Definition

SMS

The SMS object contains information about the request and details of the message information.

Key Description
message-count
integer

The amount of messages in the request
messages
array
of object's
Key Description
messages
array
of object's
Example Model
{
  "message-count": 1,
  "messages": [
    {
      "to": "447700900000",
      "message-id": "0A0000000123ABCD1",
      "status": "0",
      "remaining-balance": "3.14159265",
      "message-price": "0.03330000",
      "network": "12345"
    }
  ]
}
Example Model
<?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>
    </message>
  </messages>
</mt-submission-response>

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 None

Query Parameter

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

Request body application/x-www-form-urlencoded

Key Description Example Default
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

View response field descriptions

Response Fields

Field Description
message-count

The amount of messages in the request
messages 
{
  "message-count": 1,
  "messages": [
    {
      "to": "447700900000",
      "message-id": "0A0000000123ABCD1",
      "status": "0",
      "remaining-balance": "3.14159265",
      "message-price": "0.03330000",
      "network": "12345"
    }
  ]
}
<?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>
    </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 recieved 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. See the SMS error reference for more details

 0
message-timestamp
string

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

 2020-01-01 12:00:00 +0000
Request model
{
  "msisdn": "447700900000",
  "to": "AcmeInc",
  "network-code": "12345",
  "messageId": "0A0000001234567B",
  "price": "0.03330000",
  "status": "delivered",
  "scts": "2001011400",
  "err-code": "0",
  "message-timestamp": "2020-01-01T12:00:00.000+00:00"
}

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
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. This is typically used with short codes.

 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.

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