Email to Broadcast

Email To Broadcast System

Introduction

The Email to Broadcast service allows a registered user to send a SMS, Fax, TTS or Voice message simply by sending an email to the appropriate email address.

Authentication:
In sending an Email to Broadcast message, the sender must be authenticated as having permissions to send the message. There are three authentication methods that can be selected in the Email to Broadcast section of the user’s settings:

Challenge Response.
Once the job email is sent, the job is saved on the server, and an Authentication email is sent to the registered user address. The user replies to this to confirm that they initiated the request, and then the job is sent.
Embedded password.
In this case, the original job request should have the line “<password>xxyyzz</password>” in the body of the request. If this password matches the account password, then the message is sent immediately.
Note, the previous format of including the line “Password=xxyyzz” still works as well.

Alternatively, for advanced systems, the password can be sent in an X-Header record. To do this, your system must add the X-header: “X-EtoB-PW: yourpassword” to the email.
Email address
In this case, the only authentication is that the incoming email address is a unique address in one of the registered user accounts. This is the weakest form of authentication as email addresses are easily “spoofed” so it is possible for someone other than the account holder to send a broadcast by email under the user’s account.

Advanced options
In the user’s settings page, there are a number of advanced Email To broadcast Options that can be set.

IP WhiteList
As an additional security option, a list of allowed mail server IP addresses can be added to the “IP WhiteList” field in the user’s profile on the system. If this is set, only Email to Broadcast requests from this mail server will be accepted.

Subject Field Behaviour
Here you can select how you want text in the subject field to be treated. The options are:

Use subject field for the job name
Concatenate subject with message body. (as well as use it as the job name)

End of Message Text
This field is used to exclude email signatures from the sent message. If the user has an email signature, then the first line of the signature should be entered into this field so the signature can be excluded from the message

Use Email Body as Fax Cover
If this is set to Yes, then for Email to Fax, any text in the email will be used as the first page of the resulting fax.

Alternate Email address
Allows a different email address than the users primary address to be in the FROM address of an incoming email to broadcast message. Eg. They might have a work email address and a home email address, and this would let them send email to broadcast from both accounts.

Also, this can be set to just a domain. Eg. “mybusiness.com”, so any emails from that domain are sent out using this user’s account. This allows a whole business to send messages though one central billing account.

WhiteList Alert Email
If an email address is entered here, and a value is entered for the “IP WhiteList” field, then any attempts to send an email to broadcast from an unauthorized IP address will cause a notification email to be sent to this address.

Fax Inline Attachments
If this is turned on, then attachments marked as inline, often images and such, will be sent out as part of the Fax. Note, If this is turned on, images that are part of signature blocks will be sent as part of the fax.

X-Header-ID
See below

X-Header Parameters
For those interfacing with the Email to Broadcast system programmatically, there are a number of parameters that can be included in the email header fields. These are:

X-Header-ID
“X-Header-ID” is an alternate method of user identification. If a field called “X-Header-ID” is found in the header of an email to broadcast request, the system searches for a user with a matching “X-Header-ID” value setup in their user profile, and uses that account to send the message.

If this field is found then the sender email address is not used to identify the users account, and thus a range of people can share a single Email to Broadcast account.

Note, for backward compatibility, equivalent email header fields are “X-EtoBcode” and “X-WelCorp-ID”.

X-ReportTo
If a “X-Header-ID” field exists, then an additional field “X-ReportTo” can be added to the email header. This should consist of a valid email address, and if this is found, then job reports are sent to this address instead of the address linked to the user’s Account. This allows multiple users to send jobs and receive job reports though a single account.

X-EtoB-PW
For accounts setup with embedded password authentication, the password can be sent in a “X-EtoB-PW” header field instead of in the body of the message. “X-WelCorp-PW” is also supported for backward compatibility.

X-Receiver
In the special case where the “TO” address is not a standard xxx@yyy.message-service.org format address, as can be the case when a Mailing List is used to send Email To Broadcast requests, then the system will check for one or more “X-Receiver” header fields for appropriate xxx@yyy.message-service.org addresses, and use these to get the destination addresses.

Additional account selection options
If you can not edit the email headers, and you are stuck with a fixed sender address, you can also identify your account by adding “<EtoBcode>*my xheader id*</EtoBcode> to the start of your email body.

Usage Guide

This section outlines the procedure for a user to send a message to the Email to Broadcast system.

Email to Broadcast Services addresses:

Each email to broadcast message must specify the service that will be used to send the requested message. The message types available are Fax, SMS, Text to Speech or Voice file, and are selected by sending the email to the appropriate address:

Email to SMS: xxx@sms.message-service.org
Email to Fax: xxx@fax.message-service.org
Email to TTS: xxx@tts.message-service.org
Email to Voice: xxx@voice.message-service.org

The “xxx” should either be replaced with the destination phone number(s), or alternatively, if the numbers are included in the body of the message then the xxx can be left in place or replaced with some other placeholder text. For example: msg@sms.message-service.org

Destination Formatting:

Each message must give destination numbers as part of the message. Destinations can be specified in three ways.

In the “To” address.
For example: 0412123123@sms.message-service.org
Multiple destinations can be sent to by separating them with a “#”. Eg:
98765432#+3367473929#00116134632758@sms.message-service.org
OR, multiple destinations can be entered as multiple full email addresses:
“98765432@sms.message-service.org, +33677680275@sms.message-service.org”

Note. The part of the email address to the left of the “@” symbol can not be greater than 64 characters. This limits the number of recipients that can be sent to in one message using this method. If using multiple full email addresses, the limit is given by your email provider.
In the body of the message in the following format:
<Numbers>
98765432
+3367473929
00116134632758
</Numbers>
Lists:
The “email to broadcast” can send to lists pre-saved on the website in two ways:
1. By sending the email to list-*listname*@*type*.message-service.org
  eg: list-mycustomers@tts.message-service.org will send to your “mycustomers” list.
  Note, with this system, your saved list must not have a space or other special characters in the name.
2. By including the list names in special tags in the body of the message:
  <Lists>
  My First List Name
  My Second List Name
  </Lists>
  Note, in this case the list names can have any characters in them.

Job Name

Each Email to Broadcast message is assigned a job name in the broadcast system for tracking purposes. The “Broadcast Name” of the job is taken directly from the subject of the email.

Control parameters

Other than the message type specific commands outlined in the later relevant sections, there are some common commands that can be sent as part of a job.

<Password>
If the account is setup to use password authentication, then the tag <Password>*mypass*</Password> should be included in the body of the message.

Note for backward compatibility, the simple line “password=*mypass*” can be used instead.

Obviously, replace *mypass* for your actual account password.

<ScheduledDate>
The broadcast job can be scheduled to be sent at a later date by adding the tag <ScheduledDate>date</ScheduledDate>, where the date should be formatted as: “dd/mm/yyyy hh:mm”

Eg. <ScheduledDate>22/04/2013 15:15</ScheduledDate>

<AdditionalReportEmails>
Final job reports can be sent to additional emails other than the main account address by adding the tag:
<AdditionalReportEmails>
email1@sample.com
email2@sample.com
</AdditionalReportEmails>

Start message indicators
Instead of starting the outgoing message content at the beginning of the email, there are a couple of methods of skipping the start of the email and starting the relevant message further down.

A line containing just the tag “<Begin Message>” can be included in the email, and the outgoing content will start on the line AFTER this.
If the user has the option “Start of message text” set, then the outgoing content will start where this text is found, optionally including the text itself
Note, if the start of message text is set but not found in the incoming email, then the outgoing message will start from the beginning of the email.

End message indicators
The end of a text message to be sent can be indicated in a number of ways:

A line containing just the tag “<End Message>” can be included in the message.
A blank line followed by “– ” (two plain ascii dashes and a space) which must then be on a line by itself
Four empty lines
The text entered in the users “End of Message Text” configuration field .

The above tags and anything after will not be counted as part of the message text to send out.

Individual Service Details
This section outlines the different parameters that should be used for specific broadcast types.

Email to SMS
This will send the body of the email as an SMS to the specified recipient(s).

The message is the whole body of the email, excluding:

Anything inside a command/parameter tag. Eg.
<ScheduledDate>22/04/2013 15:15</ScheduledDate>
A Password=xxyyzz line.
Anything after one of the above specified “End Message indicators”

An error is returned if the text is longer than 445 characters.

The following optional parameters can be set in the body of the message:

<Sender>
By default the Sender number for the SMS is the users registered mobile number or “PRIVATE” if one does not exist. This can be overridden by adding the tag: <Sender>XXXXXX</Sender>

This should be a vailed mobile number, or up to 11 characters with no spaces. Eg. “MyBusiness”

<TwoWay>
The SMS can be set to 2-Way by adding the tag <TwoWay> anywhere in the email.

If this is set, then the recipient can reply to the SMS, and an email with the reply contents will be sent to the users email address. Optionally a “Default SMS reply email” address can be set for the user in the web portal, so replies go there rather than the users main email address.

<TwoWayReplyAddress>
If a SMS is set to 2-Way, then a custom email address for the replies to be sent to can be set by using this tag.

<LinkInSMSPage>
Link In SMS is a feature where custom, user specific pages of html or text data can be presented through a simple SMS message. How it works is by including <LinkInSMSPage> tags in your Email To SMS, a custom web page will be created and linked to in their SMS, allowing viewing of the page of html with a simple click. This allows a single SMS to communicate arbitrary large amounts of data. For example, a SMS broadcast could send out employee’s individual upcoming monthly timetables, or their invested stock prices, or lists of overdue library books, etc. each accessed by a simple click in their SMS.

The contents of this field should be a page of html of text data for the recipient, for example an employee’s schedule, and in your message you must include the code %%linkinsms%%. On sending, the page of data is saved to the Link In SMS server, and a link to the page is substituted into the outgoing SMS so that the recipient can easily view the linked data.

For example. Your Email to SMS message might be:

Hi Jane Smith, to view your schedule for the week, please click on %%linkinsms%%
     <LinkInSMSPage>
     <table>… {Full html table with schedule} …</table>
     </LinkInSMSPage>

Note, if your <LinkInSMSPage> field just contains a web link, then when the recipient clicks the link in the SMS, they will be redirected to your specified web page. This link can be customized for the recipient. For example:

     <LinkInSMSPage>
     http://myschedule.com/schedule.php?userid=123&auth=h6Fh89Uz.
     </LinkInSMSPage>

An alternative to using the <LinkInSMSPage> field is if you pre-upload a Recipient list through the web portal, you can include web page data for each recipient in the “Link In SMS Page” list field, and then including the code %%linkinsms%% in your SMS will add a link to html pages generated from the uploaded list. In this case you do NOT use the <LinkInSMSPage> tag, as you want the page data to come from the field in your list, not your email.

As an additional feature, in your user profile, you can set Link In SMS header and footer values, so that you can have a Logo and other links automatically wrapped around any Link In SMS html content.

<SecurityQuestion> and <SecurityAnswer>
When using Link In SMS to send medical, financial or other confidential data, you can require the user to answer a security question before viewing the linked page. To do this, simply add fields to your email like:

     <SecurityQuestion>
     Enter your birthday (dd/mm/yy) to view your results
     </SecurityQuestion>
     <SecurityAnswer>12/08/98</SecurityAnswer>

Email To Fax
This service sends one or more files attached to the email the specified recipient (s).

There must either be at least one attachment of an accepted type, or text in the body of the email. If no attachment is found then the body of the email, excluding command tags, will be used as the fax content. Optionally, an account can be configured to always use the body of the email as a cover sheet.

Regarding the email body, command tags such as “<ScheduledDate>22/04/2013 15:15</ScheduledDate>”, destination number/list tags, etc may be present, and will be stripped out of the text if the email body is included as part of the fax message.

Note, the maximum permitted total attachment size is 20MB

The following optional parameters can be set in the body of the message:

<CutOffHour>
You can specify the time after which no more faxes will be sent by adding
<CutOffHour>23:00</CutOffHour>
to the body of the message.

<FaxFromName>, <FaxCallerID>
You can modify the “From” and “Fax” header fields of the sent fax by adding one or both of the following text to the body of the email.
<FaxFromName>*Your Name* </FaxFromName>
<FaxCallerID>*Your Fax Number*</FaxCallerID>

<Resolution>
If you want to increase fax transmission speed at the cost of quality, you can set the Fax to be sent in Low Resolution by adding the line:
<Resolution>Low</Resolution>

Otherwise the best fax resolution is used.

Email to Voice
This will play one sound file attachment to a destination number.

There must be a single attachment of type “WAV”.

No other message body is required. Though “Password” and other control tags may be present.

Note, the maximum permitted total attachment size is 1.5MB

The following optional parameters can be set in the body of the message:

<CutOffHour>
You can specify the time after which no more voice messages will be sent by adding
<CutOffHour>23:00</CutOffHour>
to the body of the message.

<TwoWay>
The Voice job can be set to 2-Way by adding the tag <TwoWay> anywhere in the email. This activates return number pushed tracking, where in the final job report, the number pushed by the recipient will be displayed. This can be used for messages that say something like “Push 1 to indicate your agreement to the message”

Email to Text To Speech
This will send the body of the email as a Text to Speech message to the specified recipient(s).

The main message is the whole body of the email, excluding:

Anything inside a command/parameter tag. Eg.
<ScheduledDate>22/04/2013 15:15</ScheduledDate>
A Password=xxyyzz line.
Anything after one of the above specified “End Message indicators”

The following optional parameters can be set in the body of the message:

<CutOffHour>
You can specify the time after which no more messages will be sent by adding
<CutOffHour>23:00</CutOffHour>
to the body of the message.

<Header>
You can add a “header message” to be spoken before the main message is delivered using the <Header> tag. The purpose of this header message is to announce to the recipient the main message that is about to be delivered. For example: <Header>Hello. This is a courtesy call from XYZ Company. We are calling you as a service provided to our valued clients. The following message will be repeated for your convenience.</Header>. The header message is not repeated, while the main message is read out twice.

<NoRepeat>
The message normally is repeated for convenience of the recipient. To suppress the repeat happening, add <NoRepeat> anywhere in the email.

<VoiceMsg>
You can set an alternate message to be played for voice mail systems by adding it in the tags “<VoiceMsg>”. For example, you could add the following to your email:
<VoiceMsg>Sorry we missed you, but your library book xyz is overdue</VoiceMsg>

<Voice>
The voice used by the TTS system can be specified by including the tag <Voice>English-Kate</Voice> in the message body.

Text to Speech voices available:
“ENGLISH-ALAN” (Male Australian English)
“ENGLISH-GRACE” (Female Australian English)
“ENGLISH-ALLISON” (Female American English)
“ENGLISH-DAVE” (Male American English)
“ENGLISH-STEVEN” (Male American English)
“ENGLISH-SUSAN” (Female American English)
“ENGLISH-KATE” (Female British English)
“ENGLISH-SIMON” (Male British English)
“CHINESE-LINLIN” (Female Chinese)
“CHINESE-LISHENG” (Female Chinese)
“FRENCH-JULIETTE” (Female French)
“FRENCH-CHARLOTTE” (Female Canadian French)
“FRENCH-OLIVIER” (Male Canadian French)
“GERMAN-KATRIN” (Female German)
“LUCA-ITALIAN” (Male Italian)
“MEXICAN-ESPERANZA” (Female Mexican)
“PORTUGUESE-FELIPE” (Male Brazilian Portuguese)
“PORTUGUESE-FERNANDA” (Female Brazilian Portuguese)
“SPANISH-CARLOS” (Male American Spanish)
“SPANISH-DIEGO” (Male Argentine Spanish)
“SPANISH-FRANCISCA” (Female Chilian Spanish)
“SPANISH-SOLEDAD” (Female American Spanish)

Email to Broadcast