The SMS Save or Subscribe to SMS command allows you to add a Subscriber to send SMS messages. The Subscribe to SMS command requires the following arguments: Command, Data with Country, SMS Subscriber Phone, and SMS Sender Code in the following order.
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 subscribers with the same subscribe command. To add multiple subscribers, include additional subscribers separated by the carat (^) character. Each additional subscriber 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 Subscriber phone number and country code are always required to create an SMS subscription record. A normal Subscriber record is not necessary. The optional SMS Group ID can also be included in a command for SMS Subscribers that do not correspond to an email Subscriber.
The Phone number must be unique to a single SMS Subscriber. Attempting to add an SMS Subscription using the same Phone number for multiple subscribers will result in a failure. The SMS subscription will also fail when attempting to add with a Subscriber email that does not exist. If multiple subscribers have the same email address, you must include the first name with the email address, or use the subscriber ID, in order to associate the SMS subscription to the correct subscriber.
The Data fields supported include:
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 Subscribers.
Numeric phone number for the Subscriber. 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 Subscriber Data Fields.
Two letter country code for the Subscriber phone carrier. Only US is supported at this time.
Subscriber ID of the Subscriber to subscribe to SMS. Can be used in place of Email+First or Customer Key.
First name of the Subscriber to subscribe to SMS. Must be used with Email.
Email address of the Subscriber to subscribe to SMS. Subscriber must already exist as a regular Email subscriber, even if not subscribed to any List.
Customer Key of the Subscriber to subscribe. Subscriber must already exist as a regular Email subscriber, even if not subscribed to any List.
Group to associate SMS Subscription for sending batch messages. Group is optional.
When an SMS Subscriber 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 subscriber's desire to opt in to your list. To learn more about Force Subscribe, see the FTP API Conventions.
Using all commands and arguments (please note the command is wrapped for display purposes only, and the field order is required):
The normal Subscriber, ‘firstname.lastname@example.org’, will be subscribed to SMS Sender ‘18005559999’ in the SMS Group with ID '12'.
You can also identify the Subscriber using email and first name or subscriber ID only.
Customer Key Example
Some systems have the ability to define a unique Customer Key per subscriber. If your realm has Customer Key enabled, then you can use the customer_key in the data argument to identify the Subscriber. For example:
You can also identify the Subscriber using email and first name or subscriber ID.
The SMS Save command will fail if an invalid SMS sender code, subscriber, or SMS group is specified or if an optout is encountered for the phone number. The command will also fail if the Subscriber does not exist or an SMS subscription already exists for the specified phone number. 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 Subscriber 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)
The SMS Save command supports the following arguments:
Defines the command to use.
Subscriber related data. Phone, Country, and Sender are always required, and additional fields are optional.