Message Search API

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.

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

Query Parameter

Key Description Example Default
api_key
apiKey

You can find your API key in your account overview

abc123 None
api_secret
apiKey

You can find your API secret in your account overview

abc123 None
id
Required | string

The ID of the message you want to retrieve.

00A0B0C0 None

View response field descriptions

Response Fields

Inbound (MO)
Field Description
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.

Outbound (MT)
Field Description
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.

Inbound (MO)
Field Description
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.

Outbound (MT)
Field Description
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": "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

Query Parameter

Key Description Example Default
api_key
apiKey

You can find your API key in your account overview

abc123 None
api_secret
apiKey

You can find your API secret in your account overview

abc123 None
ids
string

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

ids=123456789&ids=987654321 None
date
string | (date)

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

2020-01-01 None
to
string

The phone number the message was sent to.

447700900000 None

View response field descriptions

Response Fields

Field Description
count
integer

The number of messages included in the response.

items
array of objects

The messages in the response.

This array contains one of the following objects:
Field Description
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.

Field Description
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.

Field Description
count
integer

The number of messages included in the response.

items
array of objects

The messages in the response.

This array contains one of the following objects:
Field Description
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.

Field Description
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.

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

Query Parameter

Key Description Example Default
api_key
apiKey

You can find your API key in your account overview

abc123 None
api_secret
apiKey

You can find your API secret in your account overview

abc123 None
date
Required | string | (date)

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

2020-01-01 None
to
Required | string

The phone number the message was sent to.

447700900000 None

View response field descriptions

Response Fields

Field Description
count
integer

The number of messages included in the response.

items
array of objects
Field Description
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.

Field Description
count
integer

The number of messages included in the response.

items
array of objects
Field Description
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": 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>