With the multimedia email API you can send images, audio, video, and more to one, or hundreds, of recipients at once. The email API
is simple to use, quick to setup and compatible with almost any application, script or programming language
that can generate an email with a specific to, subject and message body with attachments. This API has been carefully designed
to be both human and machine friendly and also supports plain text messages so you don't need to use two different API's to send
different message types.
The Email Request
A typical request consists of To:, From: and Subject: headers, a single attachment (the multimedia file) and
an email message body. For example, this message sends the image hello.jpg along with the message "Hello World"
as a WAP PUSH to mobile/cell phone number 447700912345 using the account
ANOther.61234.
This is often enough but the full set of parameters that you can specify are shown below.
Email Headers
| Tag |
Required |
Description |
| To: |
Required |
The number(s) that you wish to send the message to as an email address. <number>@itsarrived.net.
See 'SendTo' below for a programmatic way how to send your message to more than one number at the same time. |
| From: |
Required |
Normally your email program will set this for you, but this is where the response will
come back to when your message has been processed. |
| Subject: |
Required |
This must be the single word format4 |
| Attachments: |
Typically Required |
A single multimedia file to deliver to the handset(s). If you only want to send an plain text message you can omit this. |
Message Body
Message body parameters are included in the email body and are all of the form <tag>=<value>. The format of the body must be plain text only, not HTML or Rich Text. If you are using
Outlook, for example, use the Format->Plain Text menu option when composing your email.
In most cases you will only need Username, PIN and Message. You may need to use the Filename tag if your emails always get sent out with
a signature that contains an image. Otherwise that image might get sent instead of the intended one.
| Tag |
Required |
Description |
| Username |
Required |
This was sent to your email and looks something like ANOther.61234 |
| PIN |
Required |
This was sent to your mobile/cell phone and looks something like 123456 |
| ReplyTo |
Optional |
Not to be confused with the email header of the same name. This sets the originator to use for the MMS,
not the email. This setting is ignored without permission. Click here for more details of
what this can be and how you can change it. |
| SendTo |
Optional |
The number of the phone(s) that you wish to send the MMS content to (as well as the one in the To: field of the email).
The number should be in full ISO international format, including the country code.
For example 447700912345 for a UK mobile. You can put more than one number in here in which case you should separate the
numbers with a comma - for example 447700912345,447700912346. We suggest that you do not put more than
1000 numbers in each request (SendTo, SendCc and SendBcc together). Do not use this option AND multiple numbers in the To: message
header at the same time. |
| SendCc |
Optional |
Only available for use with Delivery=MMSNotification. The number of the phone(s) that you wish to Cc send the MMS content to.
The number should be in full ISO international format, including the country code.
For example 447700912345 for a UK mobile. You can put more than one number in here in which case you should separate the
numbers with a comma - for example 447700912345,447700912346. We suggest that you do not put more than
1000 numbers in each request (SendTo, SendCc and SendBcc together). Do not use this option AND multiple numbers in the To: message
header at the same time. |
| SendBcc |
Optional |
Only available for use with Delivery=MMSNotification. The number of the phone(s) that you wish to Bcc send the MMS content to.
The number should be in full ISO international format, including the country code.
For example 447700912345 for a UK mobile. You can put more than one number in here in which case you should separate the
numbers with a comma - for example 447700912345,447700912346. We suggest that you do not put more than
1000 numbers in each request (SendTo, SendCc and SendBcc together). Do not use this option AND multiple numbers in the To: message
header at the same time. |
SendTimeDelay |
Optional |
A positive integer delay in minutes up to seven days into the future (1 to 10080 minutes) to hold the
message before delivering it. |
SendTimeAbsolute |
Optional |
An ISO format date in UTC up to seven days into the future (YYYY-MM-DDThh:mm:ssZ) to hold the message
before delivering it. |
DisableContentAdaption |
Optional |
By default, repurposing of images is always on (i.e. the same as setting this to 0 of Off).
This enables you to switch off this rule by setting it to 1 or On. See above for what content adaption means. |
DisableWalledGardenRule |
Optional |
By default, we will send messages to known walled-garden networks using WAP Push even if
you specify MMS notification (i.e. the same as setting this to 0 of Off). This enables you to switch off
this rule by setting it to 1 of On. |
Message |
Recommended |
A message that will be displayed to the recipient. Typically the message invites the recipient to view the image,
listen to the music or install the java program. A maximum of 50 characters may be sent - less if the message is Unicode
encoded. |
Filename |
Optional |
If the Filename tag is used the attachment filename must match this tag in the email body.
In this case, only a file with this name will be used - any other attachments will then be ignored.
This helps protect against images in signatures or other unexpected attachments getting sent out. |
Delivery |
Optional |
By default all messages get sent out as WAP PUSH messages. If you would like to send out MMS notifications
instead then use this tag. You can specify either MMSNotification or WAPPush (the default). |
ContentType |
Optional |
You can specify the MIME type for the MMS data you are sending.
If you do not specify it, it will be determined as best possible from the attachment filename extension.
This is fine in most cases, but since only the most basic type is selected for each known extension,
you can get greater control if you specify it. |
Email Templates
If you are using Outlook 2000/2003 to compose the emails for sending SMS or MMS messages using our API's then
you can significantly speed up the process by creating a template for the email message and assigning it to a toolbar
icon. The whole process takes less than ten minutes to set-up and will save you alot of time and effort.
See the Creating An Email To SMS/MMS API Outlook Template page for more details.
Creating MMS Files
There are various toolkits available now which allow you to compile the components of an MMS into a
single .mms file. Many of them allow you to use simple drag and drop interfaces with preview so they
are ideal for anyone to use. However, if you do not know how to compile multiple items (audio, video, text, SMIL) into a
single MMS file, or need a programmatic solution to bring the components together, you can just submit a ZIP file instead
and our server will create the MMS for you.
Content Repurposing
Different phones have different capabilities: some have
small low definition colour screens other have large colour
screens; some can play complex polyphonic ringtones, other
can only play simple poly tones and other cannot play poly tones at
all. Some can display .gif images, others cannot. As a result
it is not realistic to product a single file that will
work on many phones.
The solution is to repurpose the content into a suitable
format just before delivering it to the phone. This is a
complex process that involves breaking down the original
mms file into its component parts, including the list of
recipients, and reformatting each part before re-assembling
the mms file and delivering it to the phone. All this has
to be done as soon as the phone requests the content and
before we deliver the content to the phone. Another significant
advantage of repurposing is often that we can deliver small
files to most phones - even if you provide us with a large
image.
You can send a .mms file or any other file such as .jpg
.gif .wbmp .midi .wav .amr .jad etc. We will repurpose image files
with the .jpg .gif .png and .wbmp extensions to suit the recipients
handsets. Other content, such as OTA bitmaps, sound files, and video will currently
be passed unchanged. You can disable this using the DisableRepurposing
element as described below.
Our servers are aware of the capabilities and limitations of thousands of
phones and can repurpose your content so that you can reach
the maximum number of recipients without problems.
The Email Response
After processing, the messaging server will send an email response back to the address given in the From: email header
(or ReplyTo email header if used) of the request. This details all of the messages sent and their status. For each number that you specified
to send the message to, there will be a set of five tagged values in the email response.
Message Body
| Tag |
Required |
Description |
| SendTo, SendCc or SendBcc |
Required |
The number that the message was sent to. The tag name identifies the way it was requested to
delivery it; as a standard SendTo, as a SendCc or as SendBcc. |
| MessageIdentifier |
Required |
The unique identifier for this message to this number. |
| Report |
Required |
A report code which gives the status of the processed message. |
| Text |
Required |
A text string which gives the status of the processed message. |
| LibraryNumber |
Required |
All multimedia files submitted for delivery get loaded into your private online library. This is the unique number for
the file so you can find it again. |
Examples
Sending An Image
The Email Request
From: user@mycompany.com
To: 447700912345@itsarrived.net, 4477009112233@itsarrived.net
Subject: format4
attachment: hello.jpg
Username=ANOther.61234
PIN=123456
Message=Hello World
The Email Response
From: Connection Software Support [mailto:support@csoft.co.uk]
Sent: 12 December 2006 09:39
To: user@mycompany.com
Subject: format4 result
SendTo=447700912345
MessageIdentifier=-2
Report=0
Text=Accepted by csoft: queued
LibraryNumber=94106
--
This is an automated response to your 'Email to MMS' submission sent to
Connection Software. If you have any questions you can reply to this email
and it will be sent to our support team.
All of your messages have been processed and the result for each one is
shown above.
You can view the delivery status of the messages by logging onto the website
and selecting your message history
http://www.csoft.co.uk/login
Customer Support Team
Connection Software
391 City Road
London
EC1V 1NE
United Kingdom
Telephone: +44 20 7713 8000
Fax: +44 20 7713 8001
Email: support@csoft.co.uk
Web: www.csoft.co.uk/support
|
