Email configuration via SMS
In this article we will go through configuring your mobile phone's email account.
Many phones supports POP3 and IMAP accounts, but we are going to configure a simple POP3 account as
an example.
To check emails , also an access point (APN) is needed, so we will also configure an internet connection.
Disclaimer
Not all phones that support POP3 email also support SMS configuration and not all phones have email
support.
Also, some phones don't support OTA configuration and some phones still don't support OMA
specifications.
Requirements
In order to configure properly your phone, you will need:
A POP3 email account
Your email account details, such as:
A profile name
POP3 address
SMTP address
Username
Password
An internet provider for your phone (typically a GPRS access point)
An SMS gateway which is enabled to send binary SMS (for example over http)
So, in order to be concrete, we will OTA configure a simple email account with SMTP authenticated mail
server.
Let's immagine that my email address is “julien.buratto@example.com" and that my password is
“dev.mobi".
POP3 server (to check emails) could be “pop.example.com" and the SMTP server (to send emails) could be
“smtp.example.com" and lets assume that SMTP and POP user/passwords are the same.
The profile will be called “MyEmail".
For the APN
In order to configure an internet connection (for example via GPRS), we will use the minimum details, that
is the Access Point Name, for example “web.gprsprovider.com".
Introduction
In this article we will go through configuring your mobile phone's email account.
Many phones supports POP3 and IMAP accounts, but we are going to configure a simple POP3 account as
an example.
To check emails , also an access point (APN) is needed, so we will also configure an internet connection.
Disclaimer
Not all phones that support POP3 email also support SMS configuration and not all phones have email
support.
Also, some phones don't support OTA configuration and some phones still don't support OMA
specifications.
Requirements
In order to configure properly your phone, you will need:
A POP3 email account
Your email account details, such as:
A profile name
POP3 address
SMTP address
Username
Password
An internet provider for your phone (typically a GPRS access point)
An SMS gateway which is enabled to send binary SMS (for example over http)
So, in order to be concrete, we will OTA configure a simple email account with SMTP authenticated mail
server.
Let's immagine that my email address is “julien.buratto@example.com" and that my password is
“dev.mobi".
POP3 server (to check emails) could be “pop.example.com" and the SMTP server (to send emails) could be
“smtp.example.com" and lets assume that SMTP and POP user/passwords are the same.
The profile will be called “MyEmail".
For the APN
In order to configure an internet connection (for example via GPRS), we will use the minimum details, that
is the Access Point Name, for example “web.gprsprovider.com".
The basic XML file
The code
Here is a basic XML file, please read it.
Maybe it's not that funny, but it gives a very clear understanding of what is going on; each node will be
explained step by step.
<?xml version="1.0" ?>
<!DOCTYPE wap-provisioningdoc PUBLIC "-//WAPFORUM//DTD PROV 1.0//EN"
"http://www.wapforum.org/DTD/prov.dtd">
<wap-provisioningdoc version="1.0">
<!– Let's start the list of configurations–>
<characteristic-list>
<!– This is the APN configuration –>
<characteristic type="NAPDEF">
<!– The connection ID is used internally in the configuration file –>
<parm name="NAPID" value="MyApnID"/>
<!– Connection type is GPRS –>
<parm name="BEARER" value="GSM-GPRS"/>
<!– The device will show this name for this configuration –>
<PARAM name="NAME" value="MyConnection"/>
<!– The basic APN configuration requires only the name –>
<parm name="NAP-ADDRESS" value="web.gprsprovider.com"/>
<!– We explicitely define the type of the address –>
<parm name="NAP-ADDRESS-TYPE" value="APN"/>
<!– The connection will be used for an internet web connection, not wap–>
<parm name="INTERNET" />
</characteristic>
<!– This is the configuration for POP–>
<characteristic type="APPLICATION">
<!– The APPID defines the type of application using IANA port numbers, POP is 110 –>
<parm name="APPID" value="110"/>
<!– The name for this configuration–>
<parm name="NAME" value="Mail-IN"/>
<!– To run this application, this APN/NAPDEF will be used –>
<parm name="TO-NAPID" value="MyApnID"/>
<!– This is an ID to merge POP and SMTP configuration into one applicaton –>
<parm name="PROVIDER-ID" value="OurEmailConfiguration"/>
<!– Here is the POP3 server address –>
<characteristic type="APPADDR">
<parm name="ADDR" value="pop.example.com"/>
<!– The server listens on a port–>
<characteristic type="PORT">
<!– The port is 110–>
<parm name="PORTNBR" value="110"/>
<!– IANA service is mapped to port 110 –>
<parm name="SERVICE" value="110"/>
</characteristic>
</characteristic>
<!– Let's configure the credentials, Application Authentication–>
<characteristic type="APPAUTH">
<!– Authentication type for login –>
<parm name="AAUTHTYPE" value="LOGIN"/>
<!– My username –>
<parm name="AAUTHNAME" value="julien.buratto"/>
<!– My Password –>
<parm name="AAUTHSECRET" value="dev.mobi"/>
</characteristic>
</characteristic>
<!– Let's now configure the SMTP –>
<characteristic type="APPLICATION">
<!– A service to send emails normally uses port 25–>
<parm name="APPID" value="25"/>
<!– To run this application, this APN/NAPDEF will be used –>
<parm name="TO-NAPID" value="MyApnID"/>
<!– This will be the sender of emails –>
<parm name="FROM" value="julien.buratto@example.com"/>
<!– This is the name people will see in emails –>
<parm name="NAME" value="Mail-OUT"/>
<!– This binds together the IN and OUT email account –>
<parm name="PROVIDER-ID" value="OurEmailConfiguration"/>
<!– Let's now configure the server and its port–>
<characteristic type="APPADDR">
<!– SMTP server host –>
<parm name="ADDR" value="smtp.example.com"/>
<!– SMTP server port –>
<characteristic type="PORT">
<parm name="PORTNBR" value="25"/>
<parm name="SERVICE" value="25"/>
</characteristic>
</characteristic>
<!– Let's now authenticate the SMTP connection –>
<characteristic type="APPAUTH">
<parm name="AAUTHTYPE" value="LOGIN"/>
<parm name="AAUTHNAME" value="julien.buratto"/>
<parm name="AAUTHSECRET" value="dev.mobi"/>
</characteristic>
</characteristic>
</characteristic-list>
</wap-provisioningdoc>
Explaining the code
Now lets go into the code.
If you read the XML text, you will notice a lot more things than what we expected, so here is the logic:
1. We define an access point (APN) with a NAPDEF (just mix up the letters “APN DEFinition" to get
NAPDEF) and we give it an ID called “MyApnID".
2. We define an “application" for the port 110 and we link it to the previously created APN using the
parameter TO-NAPID.
3. We define another “application" for the port 25 and we link it too to the same APN using the same
parameter TO-NAPID.
4. We link the 110 application (POP) with the 25 application (SMTP) in a single “application provider"
putting the same PROVIDER-ID called “OurEmailConfiguration" in both applications.
You have also noticed that each application has sub-characteristics.
These characteristics describe ADDRESSes, PORTs and AUTHentications for each service, that is the POP3
server address and port, the SMTP server address and port and for each one the username/password for it.
XML to WBXML
In the first article about binary SMS, we converted the XML file into WBXML by hand, checking the
documentation and converting each single TAG and character into its binary rappresentation.
This time, as the configuration is pretty long and could lead to confusion, we will introduce the use of a
LGPL library written in C which can be used to convert XML into WBXML.
I'm talking about http://libwbxml.aymerick.com/ which is under LGPL library.
Using the libwbxml library
The library is pretty easy to install; under linux you just download the library, untar the file and run “make
all" (please read INSTALL file if you encounter problems while compiling).
Once that you have finished compiling, you will have a pretty “xml2wbxml" and “wbxml2xml" files in the
tools directory.
So, just copy the XML into a text file called “ota_config.xml” and then use the xml2wbxml command to
create your binary file.
./xml2wbxml -o ota_config.wbxml ota_config.xml
The compiled WBXML file
Once that you get “xml2wbxml succeded” from the previous command, you will have a binary file called
ota_config.wbxml, please compare the orginal file to the compiled on.
-rw-r–r– 1 root root 459 2 dic 10:38 ota_config.wbxml
-rw-r–r– 1 root root 3404 2 dic 10:38 ota_config.xml
You can now understand why wbxml is so nice, the file has been converted into another file which is 7
times smaller.
How many SMS ?
As we will need to send UTF-8 chars, each SMS will allow 140 chars.
459 / 140 = 3.27 which make 4 SMS.
Prepare for the SMS gateway
In order to prepare this SMS to be sent to the sms gateway, we need to:
● Write the header of the SMS
● Convert the wbxml file into hex format
Write the User Data Header of the SMS
As described on the article “Binary SMS: sending rich content to devices using SMS”, the User Data Header
is something like “06 05 04 0B 84 23 F0” where 0B84 is the destination port for Wap Push, while 23F0 is the
source port.
In our case, the destination port is 15 7F while the source port can be 0000.
The User Data Header is then: 06 05 04 15 7F 00 00
Convert the wbxml file into hex rappresentation
In order to convert the wbxml into a hex rappresentation, you can create a file read and, for each byte,
convert it to its HEX code. A tipical example, using PHP is:
<?php
$filename="ota_config.wbxml";
$handle = fopen($filename, "r");
$binary = fread($handle, filesize($filename));
fclose($handle);
$hex=bin2hex($binary); // Convert each char into the HEX form
echo $hex.”\n”;
?>
The result is something like:
020b6a564d7941706e4944004f7572456d61696c436f6e66696775726174696f6e004c4f47494e006a756c69
656e2e6275726174746f006465762e6d6f62690063686172616374657269737469632d6c697374005041524
14d00c54601443cc65501871106830001871006ab0184500706034d79436f6e6e656374696f6e0001870806
037765622e6770727370726f76696465722e636f6d00018708032d545950450006890187140101c60001550
18736000006033131300001870706034d61696c2d494e000187220683000187000138000006830801c6000
15601873400000603706f702e6578616d706c652e636f6d0001c65301872306033131300001872406033131
3000010101c6000157018733000006831e0187000131000006832401870001320000068333010101c60001
55018736000006033235000187220683000187050346524f4d0006832403406578616d706c652e636f6d000
1870706034d61696c2d4f5554000187000138000006830801c600015601873400000603736d74702e657861
6d706c652e636f6d0001c65301872306033235000187240603323500010101c6000157018733000006831e0
1870001310000068324018700013200000683330101010101
Using a open source sms gateway – Kannel
Kannel is a open source project which aims to provide a WAP gateway for free.
Kannel can also be used to send sms messages with its “sms box”.
Explaining how to install and run Kannel is out of the scope of this article, but let's consider the simple “real
life example” where you already have a kannel installation working.
In order to sms a binary sms to kannel, you will need to submit an HTTP request to Kannel with this params:
● username and password for the kannel service
● sender and destination phone numbers
● text (the binary sms)
● udh (the user data header)
Compile the URL request
In order to pass the “020b6a…” hex rappresentation of the binary sms, you will need to add a % every 2
characters. So for example 02 should be %02 and 0b %0B and so on…
The UDH
The udh will be: %06%05%04%15%7F%00%00
The Body
The body will be:
%02%0BjVMyApnID%00OurEmailConfiguration%00LOGIN%00julien.buratto%00dev.mobi%00characteristic-list
%00PARAM%00%C5F%01D%3C%C6U%01%87%11%06%83%00%01%87%10%06%AB%01%84P
%07%06%03MyConnection%00%01%87%08%06%03web.gprsprovider.com%00%01%87%08%03-TYPE
%00%06%89%01%87%14%01%01%C6%00%01U%01%876%00%00%06%03110%00%01%87%07%06%03Mail-
IN%00%01%87%22%06%83%00%01%87%00%018%00%00%06%83%08%01%C6%00%01V
%01%874%00%00%06%03pop.example.com%00%01%C6S
%01%87%23%06%03110%00%01%87%24%06%03110%00%01%01%01%C6%00%01W
%01%873%00%00%06%83%1E
%01%87%00%011%00%00%06%83%24%01%87%00%012%00%00%06%833%01%01%01%C6%00%01U
%01%876%00%00%06%0325%00%01%87%22%06%83%00%01%87%05%03FROM
%00%06%83%24%03%40example.com%00%01%87%07%06%03Mail-OUT
%00%01%87%00%018%00%00%06%83%08%01%C6%00%01V%01%874%00%00%06%03smtp.example.com
%00%01%C6S%01%87%23%06%0325%00%01%87%24%06%0325%00%01%01%01%C6%00%01W
%01%873%00%00%06%83%1E
%01%87%00%011%00%00%06%83%24%01%87%00%012%00%00%06%833%01%01%01%01%01
This version is different for the previous one because I used a different PHP script to convert the wbxml file
to a web compatible one. I used php function URLENCODE instead of BIN2HEX.
<?php
$filename="ota_config.wbxml";
$handle = fopen($filename, "r");
$binary = fread($handle, filesize($filename));
fclose($handle);
$hex=urlencode($binary); // Take the binary file and convert to Url compatible version
echo $hex."\n";
?>
Kannel URL
At the end, the Kannel URL would be similar to:
http://my-kannel-box:15000/send-sms?username=my-kannel-username&password=my-kannelpassword&
sender=<sender phone number>&dest=<phone number of phone to configure>&udh=
%06%05%04%15%7F%00%00&text=%02%0BjVMyApnID%00OurEmailConfiguration%00LOGIN
%00julien.buratto%00dev.mobi%00characteristic-list%00PARAM%00%C5F%01D%3C%C6U
%01%87%11%06%83%00%01%87%10%06%AB%01%84P%07%06%03MyConnection
%00%01%87%08%06%03web.gprsprovider.com%00%01%87%08%03-TYPE
%00%06%89%01%87%14%01%01%C6%00%01U
%01%876%00%00%06%03110%00%01%87%07%06%03Mail-IN
%00%01%87%22%06%83%00%01%87%00%018%00%00%06%83%08%01%C6%00%01V
%01%874%00%00%06%03pop.example.com%00%01%C6S
%01%87%23%06%03110%00%01%87%24%06%03110%00%01%01%01%C6%00%01W
%01%873%00%00%06%83%1E
%01%87%00%011%00%00%06%83%24%01%87%00%012%00%00%06%833%01%01%01%C6%00%01U
%01%876%00%00%06%0325%00%01%87%22%06%83%00%01%87%05%03FROM
%00%06%83%24%03%40example.com%00%01%87%07%06%03Mail-OUT
%00%01%87%00%018%00%00%06%83%08%01%C6%00%01V
%01%874%00%00%06%03smtp.example.com%00%01%C6S
%01%87%23%06%0325%00%01%87%24%06%0325%00%01%01%01%C6%00%01W
%01%873%00%00%06%83%1E
%01%87%00%011%00%00%06%83%24%01%87%00%012%00%00%06%833%01%01%01%01%01
Reference
1. OMA Client Provisioning V.1.1 – “Provisioning Content"
http://www.openmobilealliance.org/release_program/cp_v1_1.htm
2. Nokia Series 40 Developer Platform 2.0: OMA Client Provisioning
