Bulk SMS via Email

The SMTP Bulk API lets you send SMS messages to multiple recipients with a single email, using dynamic content that is personalised for each recipient. It also works with static (identical) content.

Unlike the Email to SMS, which sends one message per email, the Bulk API accepts many recipients in one email and substitutes per-recipient fields into the message text.

Any email client that supports plain text formatting can be used, including Outlook, Outlook Express, Lotus Notes, Eudora, Elm, Pine and Unix Mail. There is no upper limit to the number of recipients per email, and multi-part (concatenated) messages are supported up to a maximum of 9 parts.

Quick Start

Compose a plain text email addressed to the bulk gateway. The To field tells the gateway where to deliver, the Subject is ignored, and everything else lives in the Body:

To: bulkgw@sms.world-text.com
Subject: (ignored — can be blank)

AccountID: 1234
APIKEY: 1234abcd6789efgh
SendID: batch3of9
Text: Please call %s at %s for more details on this position
Recipient: 447123456789|Janice|The Job Centre
Recipient: 447234567890|Charles|Lloyds Brooks
Recipient: 447345678901|Nas|The SMS Bureau

To field — bulkgw@sms.world-text.com. White label customers replace sms.world-text.com with their own domain.

Subject field — ignored, can be left blank.

Body text — a list of tag: value pairs on separate lines, containing the authentication, content and recipient information for the send. See the Tag Reference below for a full description.

Each tag must be placed on its own line with no white space before or after it.

Examples

Simple Example

Send the same static message to 3 recipients:

To: bulkgw@sms.world-text.com
Subject:

[Body Text Follows – Do not insert this line]
AccountID: 1234
APIKEY: 1234abcd6789efgh
SendID: 1
Text: Our new album is out today, buy it now at your local store.
Recipient: 447123456789
Recipient: 447234567890
Recipient: 447345678902

Send the email in Plain Text format only.

Complex Example

Send to 3 recipients with 2 dynamic fields in the message text:

To: bulkgw@sms.world-text.com
Subject:

[Body Text Follows – Do not insert this line]
AccountID: 1234
APIKEY: 1234abcd6789efgh
SendID: batch3of9
Text: Please call %s at %s for more details on this position
Recipient: 447123456789|Janice|The Job Centre
Recipient: 447234567890|Charles|Lloyds Brooks
Recipient: 447345678901|Nas|The SMS Bureau

Send the email in Plain Text format only.

Tag Reference

Tag	Description
AccountID	Account ID.
APIKEY	Account API Key.
SendID	Unique integer identifier for this send; see below for how to use it safely.
SourceAddress	Source address (sender) of the message; must be authorised on this account.
Text	The SMS message text. Special tag — see Text Tag.
Recipient	A recipient of the message. The only tag that may appear multiple times — see Recipient Tag.

SendID {#sendid}

The SendID is a unique integer identifier for a send and must only ever be used once. Any further email with the same ID is ignored until the service is restarted. This prevents external mail server errors from submitting the message multiple times.

Important: the SendID value must be unique for every send — never reuse an ID.

Text Tag {#text-tag}

The Text tag specifies the message content delivered to each handset. Write the text exactly as you want recipients to read it, and insert the character pair %s wherever a dynamic field is required. Each occurrence of %s is replaced by the corresponding fields from the Recipient Tag.

Example:

Text: Please call %s at %s for more details on this position

If multipart concatenated messages are not configured on your account, you are responsible for keeping the expanded message within 160 characters — anything longer will be truncated before it is sent.

Recipient Tag {#recipient-tag}

The Recipient tag specifies the mobile number of the recipient as well as any dynamic fields required to fully populate the message text. You are responsible for supplying the correct number of fields.

The mobile number is the only required field and must always be first. Additional fields are separated by a | (pipe) character:

Recipient: 447123456789|Janice|the job centre

Repeat the Recipient tag as many times as you need recipients.

Formatting Tags

Formatting tags control how the message text is rendered. Currently supported:

Format Tag	Description
%n	Line break. Inserts a carriage return into the message body.

Example — original SMS:

This is a test of the World-Text format tag option.

With line break tags added:

This is a%ntest of the%nWorld-Text format%ntag option.

The result:

This is a
test of the
World-Text format
tag option.

Limitations

• Rich Text and HTML format emails are not supported.
• No failure notices are provided to end users.
• The Subject field is ignored.

Related Resources

• Email to SMS
• SMS to Email Guide
• Email to SMS Service Page
• SMTP Bulk Interface Specification (PDF, May 2013)