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

Developer - Messages API Reference

Messages

The Messages API lets you retrieve messages you have sent via the SMS API by ID, as well as retrieve details of messages that were rejected.

Retrieve information about a single messages that you sent using SMS API or were received on your number.

Request

GET  https://rest.nexmo.com/search/message
Parameters

The following shows the parameters you use in the request:

Parameter Description Required
id The ID of the message you want to retrieve. Yes

Response

The following shows example Responses in JSON or XML:

Outbound Message

{
  "message-id": "0A00000000ABCD00",
  "account-id": "API_KEY",
  "network": "012345",
  "from": "Nexmo",
  "to": "447700900000",
  "body": "A text message sent using the Nexmo SMS API",
  "price": "0.03330000",
  "date-received": "2020-01-01 12:00:00",
  "final-status": "DELIVRD",
  "date-closed": "2020-01-01 12:00:00",
  "latency": 3000,
  "type": "MT"
}

Inbound Message (MO)

{
  "message-id": "0B00000053FFB40F",
  "account-id": "API_KEY",
  "network": "012345",
  "from": "447700900000",
  "to": "447700900001",
  "body": "A text message sent to Nexmo from another number",
  "date-received": "2020-01-01 12:00:00",
  "type": "MO"
}

Keys and Values

The response contains the following keys and values:

Key Value
type The message type. MT (mobile terminated or outbound) or MO (mobile originated or inbound)
message-id The id of the message you sent.
account-id Your API Key.
network The MCCMNC  for the carrier who delivered the message.
from The sender ID the message was sent from. Could be a phone number or name.
to The phone number the message was sent to.
body The body of the message
date-received The date and time at UTC+0 when Platform received your request in the following format: YYYY-MM-DD HH:MM:SS.

Fields for MT messages only

Key Value
price Price in Euros for a MT message
date-closed The date and time at UTC+0 when Platform received the delivery receipt from the carrier who delivered the MT message. This parameter is in the following format YYYY-MM-DD HH:MM:SS
latency The overall latency between date-received and date-closed in milliseconds.
client-ref The internal reference you set in the request.
final-status The status of message-id at date-closed. Possible values.
error-code-label A text label to explain error-code
status A code that explains where the message is in the delivery process. If status is not delivered check error-code for more information. If status is accepted ignore the value of error-code. Possible values.
error-code If the status is not accepted this key will have one of these possible values.

Retrieve multiple messages

Retrieve multiple messages that you sent using SMS API or were received on your number.

Request

GET  https://rest.nexmo.com/search/messages
Parameters

The following shows the parameters you use in the request:

Search by message ID

Parameter Description Required
ids The list of up to 10 message IDs to search for. For example: ids=00A0B0C0&ids=00A0B0C1&ids=00A0B0C2 Yes

or Search by recipient and date

Parameter Description Required
date The date the request to SMS API was submitted in the following format: YYYY-MM-DD Yes
to The phone number the message was sent to. Yes

Response

The following shows example Responses in JSON or XML:

{
  "count": 2,
  "items": [
    {
      "message-id": "0A00000000ABCD00",
      "account-id": "API_KEY",
      "network": "012345",
      "from": "Nexmo",
      "to": "447700900000",
      "body": "A text message sent using the Nexmo SMS API",
      "price": "0.03330000",
      "date-received": "2020-01-01 12:00:00",
      "final-status": "DELIVRD",
      "date-closed": "2020-01-01 12:00:00",
      "latency": 3000,
      "type": "MT"
    },
    {
      "message-id": "0B00000053FFB40F",
      "account-id": "API_KEY",
      "network": "012345",
      "from": "447700900000",
      "to": "447700900001",
      "body": "This is an inbound message test",
      "date-received": "2020-01-01 12:00:00",
      "type": "MO"
    }
  ]
}

Keys and Values

The response contains the following keys and values:

Key Value
type The message type. MT (mobile terminated or outbound) or MO (mobile originated or inbound)
message-id The id of the message you sent.
account-id Your API Key.
network The MCCMNC  for the carrier who delivered the message.
from The sender ID the message was sent from. Could be a phone number or name.
to The phone number the message was sent to
body The body of the message
date-received The date and time at UTC+0 when Platform received your request in the following format: YYYY-MM-DD HH:MM:SS.

Fields for MT messages only

Key Value
price Price in Euros for a MT message
date-closed The date and time at UTC+0 when Platform received the delivery receipt from the carrier who delivered the MT message. This parameter is in the following format YYYY-MM-DD HH:MM:SS
latency The overall latency between date-received and date-closed in milliseconds.
client-ref The internal reference you set in the request.
final-status The status of message-id at date-closed. Possible values.
error-code-label A text label to explain error-code
status A code that explains where the message is in the delivery process. If status is not delivered check error-code for more information. If status is accepted ignore the value of error-code. Possible values.
error-code If the status is not accepted this key will have one of these possible values.

Retrieve rejected messages

Search for messages that have been rejected by Nexmo. Messages rejected by carrier do not appear.

Request

GET  https://rest.nexmo.com/search/rejections
Parameters

The following shows the parameters you use in the request:

Parameter Description Required
date The date the request to SMS API was submitted in the following format: YYYY-MM-DD Yes
to The phone number the message was sent to. Yes

Response

The following shows example Responses in JSON or XML:

{
  "count": 1,
  "items": [
    {
      "account-id": "API_KEY",
      "from": "447700900000",
      "to": "INVALID",
      "date-received": "2020-01-01 12:00:00",
      "error-code": "3",
      "error-code-label": "to address is not numeric"
    }
  ]
}

Keys and Values

The response contains the following keys and values:

Key Value
account-id Your API Key
from Sender number
to Recipient number
date-received Date when we have received the message YYYY-MM-DD HH:MM:SS expressed in UTC time.
error-code Delivery receipt error code.
error-code-label Delivery receipt error code label.
Value Description
DELIVRD This message has been delivered to the phone number.
EXPIRED The target carrier did not send a status in the 48 hours after this message was delivered to them.
UNDELIV The target carrier failed to deliver this message.
REJECTD The target carrier rejected this message.
UNKNOWN The target carrier has returned an undocumented status code.
Value Description
delivered This message has been delivered to the phone number.
expired The target carrier did not send a status in the 48 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.
Value Description
0 Delivered.
1 Unknown - either; An unknown error was received from the carrier who tried to send this this message. or 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 or network. 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  .
Value Description
DELIVRD This message has been delivered to the phone number.
EXPIRED The target carrier did not send a status in the 48 hours after this message was delivered to them.
UNDELIV The target carrier failed to deliver this message.
REJECTD The target carrier rejected this message.
UNKNOWN The target carrier has returned an undocumented status code.
Value Description
delivered This message has been delivered to the phone number.
expired The target carrier did not send a status in the 48 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.
Value Description
0 Delivered.
1 Unknown - either; An unknown error was received from the carrier who tried to send this this message. or 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 or network. 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  .