Personal Messages API - documentation

Here, you'll find all of the technical information you need to enable you to start developing with the API.

We've tried to make it easy for you, by breaking the information down into clear areas:
before getting started and getting started.

When you have finished with this section, go to the API Manager

Personal Messages API

before getting started
getting started

before getting started

Before getting started, please read the information below, and follow any instructions.

You'll then be ready to move onto the 'getting started' section.

two things to do before you get started
all about the API manager

two things to do before you get started

To start playing with this API, please make sure you have read and understood the
Personal APIs (alpha) section

You need to be an Orange Partner Member in order to use the
Personal Messages API and access the API Manager.

If not already, become an Orange Partner member now

Access the API Manager

And then, within the API Manager, you'll be able to subscribe to the Personal Messages API.

all about the API manager

The API Manager allows you to control and configure all aspects of your Personal APIs alpha subscriptions.

Specifically you'll be able to:
gain immediate approval to use the APIs
request subscription to any or all of the APIs
gain approval for your subscription
and then receive your access key, endpoint URLs, sample codes and advanced technical documentation

The steps below describe important aspects of the interface:

The first time you log on to the API Manager, we will ask you to fill in a form to provide us with information that includes:

your website URL
your website name
your website logo

This information will help us validate your subscription.
The website information you provide will be displayed to the users to enable them to set their privacy settings, and will determine if the users will allow you - the developer - to access their personal information via the Personal APIs.

You will then have access to a screen, allowing you to request a subscription to any of the APIs.

Remember, you MUST subscribe to the Authentication API first.

Once your subscription has been validated, you will receive an email and a ZIP file containing the following:

Your access key (SERVICE_ID and SERVICE_PWD)
The API endpoint URL
Sample codes
Instructions on how to use it all.

access the API Manager

getting started

Now that you've read the 'before getting started' section, and become familiar with API Manager, you're ready to learn about...

how to authenticate the user
Personal Messages API method in detail
Personal Calendar API error codes

Also, make sure your familiar with the Personal APIs privacy management process.
The process protects Orange users by preventing third parties from accessing their personal data without their permission. Find out more

how to authenticate the user

Firstly, users need to be authenticated before access to information about their messages is granted.

The authentication is done through the Authentication API which will return a user token.

You will then include the user token in all Personal Messages API calls.

Below is an example of how the call is made:

Format:
[PersonalMessagesV2URL]?action=[action name]&
token=[user token]&param=[value]...

Example:
[PersonalMessagesV2URL]?action=getPersonalMessages&
token=Hjlkzjlfkzef23423kjlkjr&param=value...

If you want to see whether your code has worked, we can provide you with an Orange customer test account, so you can see the results as if you were an Orange customer. Once your subscription is validated, we'll show you how you can get one.

Personal Messages API method in detail

The Personal Messages API provides one method:

NEW! In the latest version of the Personal Messages API, the Personal Messages API allows you to retrieve additional information from their Orange mailbox which are the number of unread web SMS and an overview of last unread emails.

getPersonalMessages (search and retrieve information related to the messages)

getPersonalMessages (search and retrieve information related to the message)

This method retrieves the number of web SMS, the number of emails, the number of unread emails and an overview of last unread emails of a user's Orange Mailbox.

To call the API, create the following URL format in your web application and invoke it through HTTP GET:

Format:
[PersonalMessagesV2URL]?action=getPersonalMessages&
infos=[information]&token=[user token]

Example:
[PersonalMessagesV2URL]?action=getPersonalMessages&
infos=NoEMails,NoUnReadMails,NoSMS,EmailsLastNDetailed&
token=Hjlkzjlfkzef23423kjlkjr

input parameters

Name	Description	Mandatory	Type
infos	comma separated attribute list: NoEMails, NoUnReadMails, NoSMS, EmailsLastNDetailed	Yes	String
token	user token that is retrieved using the Authentication API	Yes	String

sample response

<?xml version="1.0" encoding="UTF-8"?>
    <getPersonalMessagesReturn>
        <Data>
            <UserAuthorizedData>
                  <NoUnReadMails>0</NoUnReadMails>
            </UserAuthorizedData>
            <UserProtectedData>
                  <EmailsLastNDetailed/>
            </UserProtectedData>
            <PrivacyDashboardURL>http://a.b.c/def</PrivacyDashboardURL>
        </Data>
    </getPersonalMessagesReturn>

description of the response nodes

Name	Type	Description
NoEmails	int	Number of emails in authenticated user's Orange Mailbox
NoUnReadMails	int	Number of unread emails in authenticated user's Orange Mailbox
NoSMS	int	Number of unread web SMS in authenticated user's Orange Mailbox
EmailsLastNDetailed	ixml(*)	Overview of last unread emails in authenticated user's Orange Mailbox.

Example:

  <EmailsLastNDetailed>
      <msgs>
          <msg>
                <msg_id>10</msg_id>
                <msg_from>0320202024<noreply@wanadoo.fr></msg_from>
                <msg_date>Sun, 7 Mar 2006 15:35:06 +0100 (CET)
                </msg_date>
                <msg_subject>Demande d'informations</msg_subject>
                <msg_begin_body>Bonjour, peux-tu me transmettre comme promis ta recette de crumb
                </msg_begin_body>
                <msg_url_access>http:// webmail.wanadoo.fr/webmail/fr_FR/read_syn.html?idm=10&idb=xxx
                </msg_url_access>
          </msg>
          <msg>
                <msg_id>11</msg_id>
                <msg_from>jdupont@wanadoo.fr</msg_from>
                <msg_date>Sun, 7 Mar 2006 16:12:52 +0100 (CET)
                </msg_date>
                <msg_subject>De retour de mes vacances</msg_subject>
                <msg_begin_body>Bonjour cher ami, comment se porte la famil
                </msg_begin_body>
                <msg_url_access>http:// webmail.wanadoo.fr/webmail/fr_FR/read_syn.html?idm=11&idb=xxx
                </msg_url_access>
          </msg>
      </msgs>
  </EmailsLastNDetailed>

Personal Messages API error codes

When an error occurs, the response is in the following format:

<?xml version="1.0" encoding="UTF-8"?>
  <getPersonalMessagesReturn>
      <error>
          <code>103</code>
          <detail>Error encountered. Please contact api support team with the error code number</detail>
      </error>
  </getPersonalMessagesReturn>

Here is a table which describes the error codes that are specific to that API (note: the description is given for illustrative purposes, feel free to contact the support team to get detailed feedback)

Code	Description
102, 103	Error correlated to the user's account
203, 204, 501, 503, 504, 505, 900	Internal error

(back to top)

bookmark and share

what is social bookmarking?

del.icio.us

Digg

facebook

Google

StumbleUpon

technorati