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.

Download OpenAPI 3 Specification

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
    • to
      string

      The number the message was sent to

    • message-id
      string

      The ID of the message

    • status
      string

      The status of the message

    • remaining-balance
      string

      Your remaining balance

    • message-price
      string

      The cost of the message

    • network
      string

      The ID of the network of the recipient

{
  "message-count": 1,
  "messages": [
    {
      "to": "447700900000",
      "message-id": "0A0000000123ABCD1",
      "status": "0",
      "remaining-balance": "3.14159265",
      "message-price": "0.03330000",
      "network": "12345"
    }
  ]
}

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: jsonorxml
    json
    json

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

  • 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.

    Acme Inc
    None
  • to
    Required | string

    The number that the message should be sent to

    447700900000
    None
  • text
    string

    The body of the message being sent

    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.

    false
    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, 2or3
    None
    None
  • type
    string

    Advanced: The format of the message body


    Must be one of: text, binary, wappush, unicode, vcalorvard
    text
    text
  • vcard
    string

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

    None
    None
  • vcal
    string

    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.

    https://example.com
    None

Example request

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

200 HTTP response

{
  "to": "447700900000",
  "message-id": "0A0000000123ABCD1",
  "status": "0",
  "remaining-balance": "3.14159265",
  "message-price": "0.03330000",
  "network": "12345"
}

Callback Delivery Receipt

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.

  • Key
    Description
    Example
  • msisdn
    string

    The number the message was sent to

    447700900000
  • to
    string

    The SenderID you set in from in your request

    Acme Inc
  • 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, bufferedorunknown
    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.

    Code Description
    0 Delivered.
    1 Unknown
    2 Absent Subscriber Temporary
    3 Absent Subscriber Permanent
    4 Call barred by user
    5 Portability Error
    6 Anti-Spam Rejection
    7 Handset Busy
    8 Network Error
    9 Illegal Number
    10 Invalid Message
    11 Unroutable
    12 Destination unreachable
    13 Subscriber Age Restriction
    14 Number Blocked by Carrier
    15 Pre-Paid
    99 General Error
    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

Example request

{
  "msisdn": "447700900000",
  "to": "Acme Inc",
  "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"
}

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