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

How to handle opt-in and opt-out

We require that all messaging traffic complies with relevant laws and regulations, including the Telephone Consumer Protection Act (TCPA) for the US, among others. This means there are a number of practices you must follow to comply with these regulations, respect the rights of recipients and protect your brand and reputation. These include:

Make sure recipients explicitly opt-in

Although opt-in consent isn’t needed for transactional email, to send messages to a recipient’s phone number, you must have received consent to deliver messages via this method. 

As well as complying with the TCPA, receiving clear, informed opt-in consent from recipients will also ensure higher levels of engagement and lower opt-out rates. 

To enforce opt-in for marketing and transactional SMS, we recommend the following solutions:

• Start all of your conversations with an opt-in confirmation message, verifying your recipient’s enrollment in the identified program and describing how to opt-out

• Add "Reply STOP to unsubscribe" to all messages so customers know how to opt-out.

Example: Awesome Product Welcome Message: Welcome to Awesome Product! Msg&data rates may apply. Recurring Messages. Reply HELP for help, STOP to cancel.

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.

What is a toll-free number

Toll-free numbers are different from short-code. Because there are more of them, they are cheaper than short codes but require a longer verification process from network carriers to verify whether the phone number’s owner is a legitimate business or not.

Toll-free numbers are not normal 10-digit phone numbers as they’re mostly used by businesses for marketing and transactional purposes. This makes it free for the recipient to receive communication from them, whether calls or SMS messages. As their main use case is communicating from “Application to Person” (A2P), they have a higher output than 10-digit phone numbers. 

In the US, toll-free numbers are numbers that begin with one of the following three-digit codes: 800, 888, 877, 866, 855, 844 or 833. They’re managed by the Federal Communications Commissions (FCC), which allows Responsible Organizations like MailerSend to manage subscribers of toll-free numbers.

They are used mainly for:

• Customer support 

• Text for information

• Shipping notifications

• Event or appointment reminders

• Internal communication

• Service updates

• Emergency alerts

• 2FA

Need more info?

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