How to start sending SMS

Before you can start sending SMS with MailerSend, you first need a toll-free phone number. So you can test out the SMS feature without committing to a subscription, a trial phone number is provided for all premium accounts. 

When you're ready to send more, contact our Customer Support so you can have a phone number attached to your account.

Manage your phone number

You can view and manage your phone numbers on the Phone numbers page, located beneath SMS on the left-hand navigation menu. If you don't yet have a phone number, ask our customer support to add the add-on to your subscription.

Create an SMS API token

To start sending SMS, you’ll need to use an API token. Make sure that if it’s a custom token it has the SMS permission toggled to Full access, so you have reading and writing access. You can also use an existing API token with full access. Existing tokens are retro-compatible with the SMS feature. 

For more information on how to create and manage API tokens, visit our API token management guide.

Make a request

With your language of choice or from your testing terminal, you can send a POST request to https://api.mailersend.com/v1/sms with the following request:

{
  "from": "+18332647501",
  "to": [
	" +16203221059"
  ],
  "text": "This is just a friendly hello from your friends at MailerSend."
}

Check your SMS status

After sending an SMS, you can check the status of the message in the Activity tab.

You can also see its status by querying the /sms-messages endpoint with the /{sms_message_id} from the header of the /sms endpoint’s response.

Get your SMS status by sending this GET request to the endpoint:
https://api.mailersend.com/v1/sms-messages/{sms_message_id}.

Available statuses are: processed, queued, sent, delivered and failed.

{
   "data":{
      "id":"62a75e82d8685cb6d2048fc2",
      "from":"+18332647501",
      "to":[
         "+18332552485"
      ],
      "text":"🍿 Hey this is just a friendly hello",
      "paused":false,
      "created_at":"2022-06-13T15:57:54.347000Z",
      "sms":[
         {
            "id":"62a75e83ba260242650412e2",
            "from":"+18332647501",
            "to":"+18332552485",
            "text":"🍿 Hey this is just a friendly hello",
            "status":"failed",
            "segment_count":null,
            "error_type":"opt_out",
            "error_description":"Recipient opt-out",
            "created_at":"2022-06-13T15:57:55.469000Z"
         }
      ],
      "sms_activity":[
         {
            "from":"+18332647501",
            "to":"+18332552485",
            "created_at":"2022-06-13T15:57:55.503000Z",
            "status":"failed",
            "sms_message_id":"62a75e82d8685cb6d2048fc2"
         },
         {
            "from":"+18332647501",
            "to":"+18332552485",
            "created_at":"2022-06-13T15:57:55.493000Z",
            "status":"processed",
            "sms_message_id":"62a75e82d8685cb6d2048fc2"
         }
      ]
   }
}

Provide unsubscribe instructions

For all marketing or promotional messages, you must include instructions on how to opt-out, for example, “Reply STOP to unsubscribe”. Failure to do so will result in us stopping your ability to send SMS, in accordance with our terms of use.

Commands

The STOP command

Recipients can opt-out of receiving SMS messages at any time by sending “STOP”, “Stop”, or “stop” in the text. The message doesn’t have to be comprised solely of one word, it just has to be within the text. Their phone number will be added to the “Unsubscribed” suppression list of this particular sending from number.

The START command

If a phone number is in the opt-out suppression list, they can opt back in by sending “UNSTOP", “unstop”, "START" or “start” commands in the text.

About SMS encoding and segmentation

SMS messages have character limits and if a message has more characters than the allowed limit, it is segmented into multiple parts and assembled back by the receiving device thanks to the User Data Header (UDH). 

The limits are:

• 160 characters/segment if the encoding is GSM-7

• 70 characters/segment if the encoding is UCS-2 (e.g. when using languages such as Arabic, Chinese, Korean, Japanese, or Cyrillic alphabet languages or emojis)

What is a User Data Header?

The User Data Header (UDH) takes up 6 bytes and instructs the receiving device how to reassemble the segments so that your whole message will be shown as one SMS message on the receiving handset. The maximum number of characters per concatenated (long) message is slightly reduced due to the inclusion of concatenation headers (UDH).

Encoding an SMS

The encoding used depends on the content of the message. MailerSend takes care of the encoding part for you, so whatever text editor you’re using, you don’t have to worry about it. For example, the same 355 character message has 3 segments in GSM-7 and 6 in UCS-2.

• GSM-7 is a character encoding standard used for commonly used letters and symbols in many languages

  • It uses 7 bits to send a single character/symbol on GSM networks. As SMS messages are transmitted as 140 8-bit octets at a time, GSM-7 encoded SMS messages can carry up to 160 characters (140*8/7=160)

  • You can view the basic character set for GSM-7 here

• UCS-2 is a character encoding standard used if a message cannot be encoded using GSM-7 or when a language requires more than 128 characters to be rendered

  • It uses a fixed-length 16 bits (2 bytes) to send a single character. As SMS messages are transmitted as 140 8-bit octets at a time, UCS-2 encoded messages can carry upto 70 characters {(1408) / (28) = 70}

  • UCS-2 can encode anything in the Basic Multilingual Plane

Splitting an SMS

SMS messages are split when they reach the character limit, which depends on the encoding. You can check out this tool to see what encoding your message is using and how it will be segmented.

Need more info?

Feel free to talk with us via live chat or contact us at support@mailersend.com.