Overview

The Create message API allows you to send push notifications, emails, and SMS to your users. This guide is specific for SMS and MMS. See Push notification or Email to send to those channels.

Ensure your SMS setup is complete.

Users do not need to set up SMS Subscriptions before sending SMS. If an SMS Subscription does not exist for the app, sending with include_phone_numbers automatically creates a Subscription for that phone number. The phone number must be specified using the E.164 format.

Choose a targeting strategy

Choose a strategy for targeting users with the message. Strategies include sending to:

• Aliases like External ID, Subscription ID, custom aliases, or phone numbers.
• Segments
• Filters

See Create message reference for details.

Craft your SMS or MMS message

Draft the message and embed it in the contents parameter. If you created Templates, you can use the template_id property instead of contents.

(Optional) Provide the phone number to send the SMS from in the sms_from parameter.

Refer to the below SMS parameters for additional configuration.

SMS parameters

sms_from

Type string

Description

The phone number used to send the SMS or MMS message. Defaults to the number selected in SMS Setup.

The phone number must be specified using the E.164 format.

Example

{
  "sms_from": "+15558675309"
}

contents

Type object

Description

The text message's content.

Limit each localized message's content to )

• 160 characters for GSM-7 Character Encoding
• 70 characters for UCS-2 Character Encoding

Example

{
  "contents": { 
    "en": "Welcome to Cat Facts!"
  }
}

sms_media_urls

Type string[]

Description

URLs for the media files to be attached to the text message. Your from_number must support sending MMS messages.

You may include 10 media URLs totaling up to 5 Megabytes in size.

Example

{
  "sms_media_urls": ["https://cat.com/cat.png", "https://cat.com/cat.gif"]
}

Schedule delivery

Messages are sent immediately unless you specify a specific date in which to start sending.

You can also include user-specific delivery like timezone which send to users based on their own data once the message starts sending.

See Create message reference for details.