Subscribe to SMS (SMS Save)
The SMS Save or Subscribe to SMS command allows you to add a Contact to send SMS messages. The Subscribe to SMS command requires the following arguments: Command, Data with Country, SMS Contact Phone, and SMS Sender Code in the following order.
cmd=smssave&data=country,phone,sender^US,5555091000,12016270164
The command is ‘smssave', and a subscription for the US phone number '5555091000' will be added to SMS Sender Code '12016270164' currently defined in the realm.
You can add one or many contacts with the same subscribe command. To add multiple contacts, include additional contacts separated by the carat (^) character. Each additional contact must have the same number of data fields defined.
The SMS Save command expects as least three fields in the Data argument: the SMS sender, SMS Contact phone number and country code are always required to create an SMS subscription record. A normal Contact record is not necessary. The optional SMS Group ID can also be included in a command for SMS Contacts that do not correspond to an email Contact.
cmd=smssave&data=country,phone,sender,sms_group_id^US,5555091000,12016270164,21
The Phone number must be unique to a single SMS Contact. Attempting to add an SMS Subscription using the same Phone number for multiple contacts will result in a failure. The SMS subscription will also fail when attempting to add with a Contact email that does not exist. If multiple contacts have the same email address, you must include the first name with the email address, or use the contact ID, in order to associate the SMS subscription to the correct contact.
The Data fields supported include:
Name | Field | Description |
SMS Sender | sender | Sender Code representing the message sender. A Sender Code is either a short code or number. It represents the 'from' field when deploying an SMS. The message recipient will see this sender on their mobile device when a message is received. The Sender Code must be define in the SMS UI prior to adding SMS Contacts. |
Contact Phone | phone | Numeric phone number for the Contact. Do not include special characters (such as parenthesis or dash). This SMS Phone number does not need to match that of the Phone number stored for the ContactData Fields. |
Country | country | Two letter country code for the Contact phone carrier. Only US is supported at this time. |
Contact ID | subscriber_id | Contact ID of the Contact to subscribe to SMS. Can be used in place of Email+First or Customer Key. |
First Name | first | First name of the Contact to subscribe to SMS. Must be used with Email. |
Email address of the Contact to subscribe to SMS. Contact must already exist as a regular Email contact, even if not subscribed to any List. | ||
Customer Key | customer_key | Customer Key of the Contact to subscribe. Contact must already exist as a regular Email contact, even if not subscribed to any List. |
SMS Group | sms_group_id | Group to associate SMS Subscription for sending batch messages. Group is optional. |
Resubscribe
When an SMS Contact opts out of future messages by sending a STOP request, an Opt Out record is created which prevents both future subscriptions and sending future messages. To override an opt out you must use the force_subscribe argument in the header of your FTP file. This should only be used in very specific cases in which you have verified the contact's desire to opt in to your list. To learn more about Force Subscribe, see the FTP API Conventions.
Example
Using all commands and arguments (please note the command is wrapped for display purposes only, and the field order is required):
cmd=smssave&data=country,phone,subscriber_id,sender,first,email,sms_group_id^US,5555555008,555,120162701645,Jane,jane@domain.com,12
The normal Contact, ‘jane@domain.com’, will be subscribed to SMS Sender ‘18005559999’ in the SMS Group with ID '12'.
You can also identify the Contact using email and first name or contact ID only.
cmd=smssave&data=country,phone,subscriber_id,sender,first,email,sms_group_id^US,5555555008,,120162701645,Jane,jane@domain.com,12
cmd=smssave&data=country,phone,subscriber_id,sender,first,email,sms_group_id^US,5555555008,555,120162701645,,12
Customer Key Example
Some systems have the ability to define a unique Customer Key per contact. If your realm has Customer Key enabled, then you can use the customer_key in the data argument to identify the Contact. For example:
cmd=smssave&data=country,phone,subscriber_id,sender,first,email,customer_key,sms_group_id^US,5555555008,,120162701645,,,555Jane,12
You can also identify the Contact using email and first name or contact ID.
cmd=smssave&data=country,phone,subscriber_id,sender,first,email,customer_key,sms_group_id^US,5555555008,,120162701645,Jane,jane@domain.com,,12
cmd=smssave&data=country,phone,subscriber_id,sender,first,email,customer_key,sms_group_id^US,5555555008,555,120162701645,,,12
Errors
The SMS Save command will fail if the SMS feature is not enabled for the realm. It will also fail if an invalid SMS sender code, contact, or SMS group is specified or if an optout is encountered for the phone number. The command will also fail if the Contact does not exist or an SMS subscription already exists for the specified phone number. It does not validate that the Contacts Phone matches the SMS Phone. Several example errors include:
SMS Sender could not be found for sender code
An SMS Subscription already exists
Country, Sender Code, Phone cannot be empty
Phone should only contain numeric digits
SMS Group could not be found with ID
Country Code is not supported (only US is supported at this time)
Email Contact could not be retrieved with the provided information.
Array index out of range (number of fields defined does not match number of data fields in command)
Arguments
The SMS Save command supports the following arguments:
Name | Req? | Description | Argument |
Command | Yes | Defines the command to use. | cmd=smssave |
Data | Yes | Contact related data. Phone, Country, and Sender are always required, and additional fields are optional. | data=[fields] |