Available Operations
 
 

Message Search API

The Message Search API is deprecated

Please use the Reports API instead. See the Migrating from the SMS Message Search API guide to get started.

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.

Available Operations:

Get a single message

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

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

Query Parameter

api_key
apiKey

You can find your API key in your account overview

api_secret
apiKey

You can find your API secret in your account overview

id
string | Required

The ID of the message you want to retrieve.

Responses

200 OK
type
string

The message type. MT (mobile terminated or outbound) or MO (mobile originated or inbound)

One of: MO
message-id
string

The id of the message you sent.

account-id
string

Your API Key.

date-received
string

The date and time at UTC+0 when Platform received your request in the following format: YYYY-MM-DD HH:MM:SS.

network
string

The MCCMNC for the carrier who delivered the message.

from
string

The sender ID the message was sent from. Could be a phone number or name.

to
string

The phone number the message was sent to.

body
string

The body of the message.

type
string

The message type. MT (mobile terminated or outbound) or MO (mobile originated or inbound)

One of: MT
message-id
string

The id of the message you sent.

account-id
string

Your API Key.

network
string

The MCCMNC for the carrier who delivered the message.

from
string

The sender ID the message was sent from. Could be a phone number or name.

to
string

The phone number the message was sent to.

body
string

The body of the message.

date-received
string

The date and time at UTC+0 when Platform received your request in the following format: YYYY-MM-DD HH:MM:SS.

price
number

Price in Euros for a MT message.

date-closed
string

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
number

The overall latency between date-received and date-closed in milliseconds.

client-ref
string

The internal reference you set in the request.

status
string

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.

One of: delivered, expired, failed, rejected, accepted, buffered or unknown
final-status
string

The status of message-id at date-closed.

One of: DELIVRD, EXPIRED, UNDELIV, REJECTD or UNKNOWN
error-code
string

Will be set if the status is not accepted.

One of: 0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 99, 400 or 401
error-code-label
string

A text label to explain error-code.

type
string

The message type. MT (mobile terminated or outbound) or MO (mobile originated or inbound)

One of: MO
message-id
string

The id of the message you sent.

account-id
string

Your API Key.

date-received
string

The date and time at UTC+0 when Platform received your request in the following format: YYYY-MM-DD HH:MM:SS.

network
string

The MCCMNC for the carrier who delivered the message.

from
string

The sender ID the message was sent from. Could be a phone number or name.

to
string

The phone number the message was sent to.

body
string

The body of the message.

type
string

The message type. MT (mobile terminated or outbound) or MO (mobile originated or inbound)

One of: MT
message-id
string

The id of the message you sent.

account-id
string

Your API Key.

network
string

The MCCMNC for the carrier who delivered the message.

from
string

The sender ID the message was sent from. Could be a phone number or name.

to
string

The phone number the message was sent to.

body
string

The body of the message.

date-received
string

The date and time at UTC+0 when Platform received your request in the following format: YYYY-MM-DD HH:MM:SS.

price
number

Price in Euros for a MT message.

date-closed
string

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
number

The overall latency between date-received and date-closed in milliseconds.

client-ref
string

The internal reference you set in the request.

status
string

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.

One of: delivered, expired, failed, rejected, accepted, buffered or unknown
final-status
string

The status of message-id at date-closed.

One of: DELIVRD, EXPIRED, UNDELIV, REJECTD or UNKNOWN
error-code
string

Will be set if the status is not accepted.

One of: 0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 99, 400 or 401
error-code-label
string

A text label to explain error-code.

Example Responses

200 400 401
{
  "type": "MO",
  "message-id": "0A00000000ABCD00",
  "account-id": "API_KEY",
  "date-received": "2020-01-01 12:00:00",
  "network": "012345",
  "from": "Nexmo",
  "to": "447700900000",
  "body": "A text message sent using the Nexmo SMS API"
}
{
  "type": "MT",
  "message-id": "0A00000000ABCD00",
  "account-id": "API_KEY",
  "network": "012345",
  "from": "Nexmo",
  "to": "447700900000",
  "body": "A text message sent using the Nexmo SMS API",
  "date-received": "2020-01-01 12:00:00",
  "price": 0.0333,
  "date-closed": "2020-01-01 12:00:00",
  "latency": 3000,
  "client-ref": "my-personal-reference",
  "status": "abc123",
  "final-status": "DELIVRD",
  "error-code": "0",
  "error-code-label": "Delivered"
}
<?xml version="1.0" encoding="UTF-8"?>
<message>
  <type>MO</type>
  <message-id>0A00000000ABCD00</message-id>
  <account-id>API_KEY</account-id>
  <date-received>2020-01-01 12:00:00</date-received>
  <network>012345</network>
  <from>Nexmo</from>
  <to>447700900000</to>
  <body>A text message sent using the Nexmo SMS API</body>
</message>
<?xml version="1.0" encoding="UTF-8"?>
<message>
  <type>MT</type>
  <message-id>0A00000000ABCD00</message-id>
  <account-id>API_KEY</account-id>
  <network>012345</network>
  <from>Nexmo</from>
  <to>447700900000</to>
  <body>A text message sent using the Nexmo SMS API</body>
  <date-received>2020-01-01 12:00:00</date-received>
  <price>0.0333</price>
  <date-closed>2020-01-01 12:00:00</date-closed>
  <latency>3000</latency>
  <client-ref>my-personal-reference</client-ref>
  <status>abc123</status>
  <final-status>DELIVRD</final-status>
  <error-code>0</error-code>
  <error-code-label>Delivered</error-code-label>
</message>
{
  "type": "BAD_REQUEST",
  "error_title": "Bad Request",
  "invalid_parameters": {}
}
<?xml version="1.0" encoding="UTF-8"?>
<error>
  <type>BAD_REQUEST</type>
  <error_title>Bad Request</error_title>
  <invalid_parameters>
    <invalid_parameter>
      <key>date</key>
      <value>Is required.</value>
    </invalid_parameter>
  </invalid_parameters>
</error>
{
  "error-code": "0",
  "error-code-label": "Delivered"
}
<?xml version="1.0" encoding="UTF-8"?>
<hash>
  <error-code>0</error-code>
  <error-code-label>Delivered</error-code-label>
</hash>

Search messages

Retrieve multiple messages that you sent using the SMS API or that were received on your number. You may provide one or more ids are specified, or both date and number to identify the messages.

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

Query Parameter

api_key
apiKey

You can find your API key in your account overview

api_secret
apiKey

You can find your API secret in your account overview

ids
string

A message ID to search for. You can specify up to 10 message IDs to search for as query parameters.

date
string (date)

The date the request to SMS API was submitted in the following format: YYYY-MM-DD

to
string

The phone number the message was sent to.

Responses

200 OK
count
integer

The number of messages included in the response.

items
array of objects

The messages in the response.

count
integer

The number of messages included in the response.

items
array of objects

The messages in the response.

Example Responses

200 400 401
{
  "count": 1,
  "items": [
    {
      "type": "MO",
      "message-id": "0A00000000ABCD00",
      "account-id": "API_KEY",
      "date-received": "2020-01-01 12:00:00",
      "network": "012345",
      "from": "Nexmo",
      "to": "447700900000",
      "body": "A text message sent using the Nexmo SMS API"
    },
    {
      "type": "MT",
      "message-id": "0A00000000ABCD00",
      "account-id": "API_KEY",
      "network": "012345",
      "from": "Nexmo",
      "to": "447700900000",
      "body": "A text message sent using the Nexmo SMS API",
      "date-received": "2020-01-01 12:00:00",
      "price": 0.0333,
      "date-closed": "2020-01-01 12:00:00",
      "latency": 3000,
      "client-ref": "my-personal-reference",
      "status": "abc123",
      "final-status": "DELIVRD",
      "error-code": "0",
      "error-code-label": "Delivered"
    }
  ]
}
<?xml version="1.0" encoding="UTF-8"?>
<hash>
  <count>1</count>
  <items>
    <item>
      <type>MO</type>
      <message-id>0A00000000ABCD00</message-id>
      <account-id>API_KEY</account-id>
      <date-received>2020-01-01 12:00:00</date-received>
      <network>012345</network>
      <from>Nexmo</from>
      <to>447700900000</to>
      <body>A text message sent using the Nexmo SMS API</body>
    </item>
    <item>
      <type>MT</type>
      <message-id>0A00000000ABCD00</message-id>
      <account-id>API_KEY</account-id>
      <network>012345</network>
      <from>Nexmo</from>
      <to>447700900000</to>
      <body>A text message sent using the Nexmo SMS API</body>
      <date-received>2020-01-01 12:00:00</date-received>
      <price>0.0333</price>
      <date-closed>2020-01-01 12:00:00</date-closed>
      <latency>3000</latency>
      <client-ref>my-personal-reference</client-ref>
      <status>abc123</status>
      <final-status>DELIVRD</final-status>
      <error-code>0</error-code>
      <error-code-label>Delivered</error-code-label>
    </item>
  </items>
</hash>
{
  "type": "BAD_REQUEST",
  "error_title": "Bad Request",
  "invalid_parameters": {}
}
<?xml version="1.0" encoding="UTF-8"?>
<error>
  <type>BAD_REQUEST</type>
  <error_title>Bad Request</error_title>
  <invalid_parameters>
    <invalid_parameter>
      <key>date</key>
      <value>Is required.</value>
    </invalid_parameter>
  </invalid_parameters>
</error>
{
  "error-code": "0",
  "error-code-label": "Delivered"
}
<?xml version="1.0" encoding="UTF-8"?>
<hash>
  <error-code>0</error-code>
  <error-code-label>Delivered</error-code-label>
</hash>

Search for rejections

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

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

Query Parameter

api_key
apiKey

You can find your API key in your account overview

api_secret
apiKey

You can find your API secret in your account overview

date
string (date) | Required

The date the request to SMS API was submitted in the following format: YYYY-MM-DD

to
string | Required

The phone number the message was sent to.

Responses

200 OK
count
integer

The number of messages included in the response.

items
array of objects
account-id
string

Your API Key.

from
string

The sender ID the message was sent from. Could be a phone number or name.

to
string

The phone number the message was sent to.

date-received
string

The date and time at UTC+0 when Platform received your request in the following format: YYYY-MM-DD HH:MM:SS.

error-code
string

Will be set if the status is not accepted.

One of: 0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 99, 400 or 401
error-code-label
string

A text label to explain error-code.

count
integer

The number of messages included in the response.

items
array of objects
account-id
string

Your API Key.

from
string

The sender ID the message was sent from. Could be a phone number or name.

to
string

The phone number the message was sent to.

date-received
string

The date and time at UTC+0 when Platform received your request in the following format: YYYY-MM-DD HH:MM:SS.

error-code
string

Will be set if the status is not accepted.

One of: 0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 99, 400 or 401
error-code-label
string

A text label to explain error-code.

Example Responses

200 400 401
{
  "count": 1,
  "items": [
    {
      "account-id": "API_KEY",
      "from": "Nexmo",
      "to": "447700900000",
      "date-received": "2020-01-01 12:00:00",
      "error-code": "0",
      "error-code-label": "Delivered"
    }
  ]
}
<?xml version="1.0" encoding="UTF-8"?>
<hash>
  <count>1</count>
  <items>
    <item>
      <account-id>API_KEY</account-id>
      <from>Nexmo</from>
      <to>447700900000</to>
      <date-received>2020-01-01 12:00:00</date-received>
      <error-code>0</error-code>
      <error-code-label>Delivered</error-code-label>
    </item>
  </items>
</hash>
{
  "type": "BAD_REQUEST",
  "error_title": "Bad Request",
  "invalid_parameters": {}
}
<?xml version="1.0" encoding="UTF-8"?>
<error>
  <type>BAD_REQUEST</type>
  <error_title>Bad Request</error_title>
  <invalid_parameters>
    <invalid_parameter>
      <key>date</key>
      <value>Is required.</value>
    </invalid_parameter>
  </invalid_parameters>
</error>
{
  "error-code": "0",
  "error-code-label": "Delivered"
}
<?xml version="1.0" encoding="UTF-8"?>
<hash>
  <error-code>0</error-code>
  <error-code-label>Delivered</error-code-label>
</hash>