Search SMS Messages

GET /api/sms/{phone_number}/messages

This endpoint returns the latest SMS messages for a given phone number.

Example

cURL

curl --request GET \
     --url https://api.mailisk.com/api/sms/{phone_number}/messages \
     --header 'Accept: application/json' \
     --header 'X-Api-Key: {Api Key}' \
     --get \
     --data-urlencode 'body=test message'

Node

const { data: smsMessages } = await mailisk.searchSms(phoneNumber, {
  body: "test message",
});

WARNING

The mailisk and cypress-mailisk libraries default to using the wait flag. This means the request will keep waiting till at least one matching SMS message is returned. While direct use of the API does not have this flag, it can be added manually.

Response

{
  "total_count": 1,
  "options": {
    "limit": 20,
    "offset": 0
  },
  "data": [
    {
      "id": "37a2bc57-c2c7-4c08-a9dc-d143bc17643f",
      "sms_phone_number_id": "ba548be2-bff9-4e3f-a54b-e034c415e906",
      "body": "test newline \\n\\n test2",
      "from_number": "+18777804236",
      "to_number": "+19285639871",
      "provider_message_id": "SMf72eb72b6281a02e60a0114f38e34e36",
      "created_at": "2020-11-24T16:48:22.170Z",
      "direction": "inbound"
    }
  ]
}

Waiting for SMS

When waiting to receive SMS you can use the wait parameter instead of querying multiple times. This will keep redirecting to the same request until the result would return at least one matching SMS (total_count >= 1).

This can be combined with the other parameters like from_number and body to listen for specific SMS messages.

WARNING

Since this request will never timeout you should set a timeout in your integration tests.

Request

Path Params

Name	Description
phone_number	The phone number to get messages from. E.g. 1234567890

Query

Name	Required	Type	Description
limit	Optional	Number	The maximum number of messages that can be returned in this request. Must be between 1 and 100
offset	Optional	Number	The number of messages to skip/ignore, useful for pagination.
body	Optional	String	The body of the message to search for. Case insensitive search.
from_number	Optional	String	The from number of the message to search for. Searched as prefix meaning +123 would return all messages where the sender number starts with +123.
from_date	Optional	Date	The date to search for messages from.
to_date	Optional	Date	The date to search for messages to.
wait	Optional	Boolean	If this flag is true then the request will keep waiting till at least one response is returned. See Waiting for SMS.

Response

Typescript type

interface SmsMessage {
  /** Unique identifier for the message */
  id: string;
  /** Unique identifier for the SMS phone number */
  sms_phone_number_id: string;
  /** Body of the message */
  body: string;
  /** From number of the message */
  from_number: string;
  /** To number of the message */
  to_number: string;
  /** Provider message ID */
  provider_message_id?: string;
  /** Date and time the message was created */
  created_at: string;
  /** Direction of the message */
  direction: "inbound" | "outbound";
}