SMS

/api/sms

The SMS API lets you list your Mailisk SMS numbers, search messages delivered to a number, and send virtual SMS messages into numbers you own for testing.

Endpoints

Method	Endpoint	Description
GET	/api/sms/{phone_number}/messages	Search SMS messages for a phone number
GET	/api/sms/numbers	List SMS numbers available to the API key
POST	/api/sms/virtual	Send a virtual SMS to a number you own

Search SMS Messages

GET /api/sms/{phone_number}/messages

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

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.searchSmsMessages(phoneNumber, {
  body: 'test message',
});

WARNING

The mailisk and cypress-mailisk libraries default to using the wait flag. This means the request will keep waiting until at least one matching SMS message is returned. Direct API requests do not use this flag by default, but it can be added manually.

Waiting for SMS

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

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

WARNING

Since this request will never timeout on its own, set a timeout in your integration tests.

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 or ignore, useful for pagination.
body	Optional	String	The body of the message to search for. Search is case insensitive.
from_number	Optional	String	The from number of the message to search for. Searched as a prefix, meaning +123 returns 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 until at least one response is returned. See Waiting for SMS.

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

List SMS Numbers

GET /api/sms/numbers

This endpoint returns all SMS numbers available to the current user. This includes requested, active, and disabled numbers.

cURL

curl --request GET \
     --url https://api.mailisk.com/api/sms/numbers \
     --header 'Accept: application/json' \
     --header 'X-Api-Key: {Api Key}'

Node

const { data: numbers } = await mailisk.listSmsNumbers();

Response

{
  "total_count": 2,
  "data": [
    {
      "id": "13c4551e-a5be-4959-9ea5-82931dcfc74d",
      "organisation_id": "c02bdb84-22df-4c18-85ba-2defdd04eccb",
      "status": "requested",
      "country": "US",
      "created_at": "2020-11-22T16:59:25.462Z",
      "updated_at": "2020-11-22T16:59:25.462Z"
    },
    {
      "id": "6bf073d6-d333-45c9-b009-c77f0cac7657",
      "organisation_id": "ddec2c7b-b087-45b6-a81d-b195f25d457f",
      "status": "active",
      "country": "US",
      "phone_number": "+19285639871",
      "created_at": "2020-11-22T16:41:40.329Z",
      "updated_at": "2020-11-22T16:41:40.329Z"
    }
  ]
}

Send Virtual SMS

POST /api/sms/virtual

This endpoint allows you to send a virtual SMS message to a phone number you own.

cURL

curl --request POST \
     --url https://api.mailisk.com/api/sms/virtual \
     --header 'Accept: application/json' \
     --header 'Content-Type: application/json' \
     --header 'X-Api-Key: {Api Key}' \
     --data '{
       "from_number": "1234567890",
       "to_number": "1234567890",
       "body": "Hello, world!"
     }'

Node

await mailisk.sendVirtualSms({
  from_number: '15551234567',
  to_number: '15557654321',
  body: 'Test message',
});

Body

Name	Required	Type	Description
from_number	Required	String	The phone number to send the SMS from. E.g. 1234567890.
to_number	Required	String	The phone number to send the SMS to. This must be a number you own. E.g. 1234567890.
body	Required	String	The body of the SMS message. E.g. Hello, world!.

Response

Successful requests return 201 Created with an empty body.

Typescript types

interface SmsNumberListResponse {
  total_count: number;
  data: SmsNumber[];
}

interface SmsNumber {
  /** Unique identifier for the SMS number */
  id: string;
  /** Unique identifier for the organisation */
  organisation_id: string;
  /** Status of the SMS number */
  status: 'requested' | 'active' | 'disabled';
  /** Country of the SMS number */
  country: string;
  /** SMS phone number */
  phone_number?: string | null;
  /** Whether this number is a test number */
  is_test_number?: boolean;
  /** Date and time the SMS number was created */
  created_at: string;
  /** Date and time the SMS number was updated */
  updated_at: string;
}

interface SmsMessageListResponse {
  total_count: number;
  options: {
    limit: number;
    offset: number;
    body?: string;
    from_number?: string;
    from_date?: string;
    to_date?: string;
    wait?: boolean;
  };
  data: SmsMessage[];
}

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 | null;
  /** Date and time the message was created */
  created_at: string;
  /** Direction of the message */
  direction: 'inbound' | 'outbound';
}