Getting Started

OpenMail opens up AOL mail data. What can it do? See our Overview. Ready to try out the Mail Open Services? See the Getting Started Guide.

Once you have a devId, you can get started with samples and the Open Service API Reference.

If you need help, check out the OpenMail Forums and the FAQ.


API Docs

OpenMail API Methods

New Mail Count Service

This service has two primary objectives:

  • Provide a simple interface to service client requests for this data using XML-RPC over HTTP(S) protocol
  • Return data in JSON or XML formats.

newMailCount

Description

newMailCount provides the count of the new mails. At present, counts are limited to Inbox and Voicemail folders. The returned values represent the actual number of "new" entries in a folder and the last time that the cache entry was updated. In this context, "new" means messages that are neither flagged with the IMAP 'deleted' nor 'seen' flags.

URL

http(s)://api.mail.aol.com/mail/newMailCount

Required Parameters

* f
the response format (xml, json). You can choose xml or json based results.
* a
a valid AOL authentication token. The token extracted after authentication from OpenAuth
* devId
Developer ID (or AKES key) assigned to the invoking app. You can get a developerID by registering at http://dev.aol.com/keys
* referer
the value of the URL making the request. It may be provided as a query parameter or HTTP header. If nothing is specified, the default referer value is taken.

Optional Parameters

* c
The callback function to invoke in the response (appropriate for JSON responses only).
* r
an URL safe string to be used as requestId - when passed it is returned back in the response

Sample XML Response

<response>
  <statusCode>200</statusCode>
  <statusText>OK</statusText>
  <statusDetailCode>0</statusDetailCode>>
  <data>
    <mailFolderCount>
      <lastUpdate>2006-09-08T16:48:40-05:00</lastUpdate>
      <mailFolderData>
        <mailFolderType>
          <name>INBOX</name>
          <class>Test Inbox Folder</class>
          <count>1</count>
          <limit>1000</limit>
       </mailFolderType>
     </mailFolderData>
   </mailFolderCount>
  </data>
</response>

The above XML is based on the following XML Schema: 

<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema" elementFormDefault="qualified"> 
  <xs:element name="response" type="responseType"/> 
  <xs:complexType name="responseType"> 
    <xs:sequence> 
      <xs:element name="statusCode" type="xs:int" minOccurs="1" maxOccurs="1"/> 
      <xs:element name="statusText" type="xs:string" minOccurs="1" maxOccurs="1"/>
      <xs:element name="statusDetailCode" type="xs:int" minOccurs="0" maxOccurs="1"/> 
      <xs:element name="requestId" type="xs:string" minOccurs="0" maxOccurs="1"/>
      <xs:element name="data" type="dataType" minOccurs="1" maxOccurs="1"/> 
    </xs:sequence> 
  </xs:complexType> 
  <xs:complexType name="dataType"> 
    <xs:all> 
      <xs:element name="mailFolderCount" type="mailFolderCountDict" minOccurs="0"/> 
    </xs:all> 
  </xs:complexType> 
  <xs:complexType name="mailFolderTypeDict"> 
    <xs:all> 
      <xs:element name="name" type="xs:string" minOccurs="1"/> 
      <xs:element name="class" type="xs:string" minOccurs="1"/> 
      <xs:element name="count" type="xs:int" minOccurs="1"/> 
     <xs:element name="limit" type="xs:int" minOccurs="1"/> 
    </xs:all> 
  </xs:complexType> 
  <xs:complexType name="mailFolderCountDict"> 
    <xs:all> 
      <xs:element name="lastUpdate" type="xs:string" minOccurs="1"/> 
      <xs:element name="mailFolderData" type="mailFolderDataArray" minOccurs="1"/> 
    </xs:all> 
  </xs:complexType> 
  <xs:complexType name="mailFolderDataArray"> 
  <xs:sequence> 
    <xs:element name="mailFolderType" type="mailFolderTypeDict" minOccurs="2" maxOccurs="2"/> 
  </xs:sequence> 
  </xs:complexType> 
</xs:schema>

Sample JSON Response

{
"response":{
  "statusCode":200 "statusText":OK "statusDetailCode":0"data":{ 
    "mailFolderCount": {
      "lastUpdate":"2006-10-16T16:53:55-05:00" "mailFolderData": {
        "mailFolderType":[ { 
          "name":"INBOX", "class":"Test Inbox Folder", "count":"1", 
					"limit":"1000" }, { 
          "name":"VOICEMAIL", "class":"Test VoiceMail Folder", 
					"count":"1", "limit":"1000" } ]
      }
    }
  }
}}

Error Codes

200 - Success (Ok)

451 - Permission Denied

460 - Missing required parameter

462 - Parameter error

408 - Request Timeout

500 - Generic Server Error

Note: For OpenAuth error codes, consult http://dev.aol.com/openauth_api

New Mail List Service

Description

The New Mail List Service is also an XML-RPC service available via a "GET" request over HTTP(S) The New Mail List Service has the following features:

  • Return data in user specified format (xml, json).
  • Only new mail is returned. New mail is defined as mail that has not been seen, mail marked as unread, or mail flagged as keep as new
  • If the folder name parameter is absent in the request, the contents of Inbox and Voicemail folders are returned. Currently supported values for foldernames are Inbox and Voicemail.

URL

http(s)://api.mail.aol.com/mail/newMailList

Required Parameters

* f
the response format (xml, json). You can choose xml or json based results.
* a
a valid AOL authentication token. The token extracted after authentication from OpenAuth
* devId
Developer ID (or AKES key) assigned to the invoking app. You can get a developerID by registering at http://dev.aol.com/keys
* referer
the value of the URL making the request. It may be provided as a query parameter or HTTP header. If nothing is specified, the default referer value is taken.

Optional Parameters

* folder
the folder to list mail from. Supported values are Inbox, Voicemail. Default assumes both Inbox and Voicemail.
* items
The number of mail items to retrieve. This number cannot be greater than a system defined limit (75). If this parameter is unspecified, the number of items returned will be 10.
* c
The callback function to invoke in the response (for JSON responses only).
* r
an URL safe string to be used as requestId - when passed it is returned back in the response
* lang
language value (applicable to the Deep Link URL only). Default value is "en"
* locale
locale value (applicable to the Deep Link URL only). Default value is "us"
* showCount
Parameter to indicate whether the list response should contain the total new mail count for the folder. Valid values are yes or no. If the value is present and the value is yes, the list response will contain a 'totalCount' element to indicate the total new mail count. The 'totalCount' element will be absent if the value is absent or the value is no.

Sample XML Response Structure

<response> 
  <statusCode /> 
  <statusText /> 
  <statusDetailCode /> 
  <requestId /> 
  <data> 
    <mailList> 
      <lastUpdate /> 
      <messageLimit /> 
        <messageList> 
          <folderMessages> 
           <folderName /> 
           <messageCount /> 
           <totalCount /> 
           <messages> 
             <messageElement> 
               <sender /> 
               <subject /> 
               <sentOn /> 
               <seen /> 
               <deleted /> 
               <read /> 
               <hasAttachment /> 
               <hasEmbed /> 
               <classification /> 
               <messageIconLink /> 
               <messageLink /> 
               <digest /> 
             </messageElement> 
           </messages> 
          </folderMessages> 
        </messageList> 
    </mailList> 
  </data> 
</response>

Response XML Schema 

<?xml version="1.0" encoding="UTF-8"?> 
  <xs:schemaxmlns:xs="http://www.w3.org/2001/XMLSchema" elementFormDefault="qualified"> 
  <xs:element name="response" type="responseType"/> 
  <xs:complexType name="responseType"> 
    <xs:sequence> 
	<xs:element name="statusCode" type="xs:int" minOccurs="1" maxOccurs="1"/> 
    <xs:element name="statusText" type="xs:string" minOccurs="1" maxOccurs="1"/> 
	<xs:element name="statusDetailCode" type="xs:int" minOccurs="1" maxOccurs="1"/> 
	<xs:element name="requestId" type="xs:string" minOccurs="0" maxOccurs="1"/> 
	<xs:element name="data" type="dataType" minOccurs="1" maxOccurs="1"/> 
    </xs:sequence> 
  </xs:complexType> 
  <xs:complexType name="dataType"> 
    <xs:all> 
	<xs:element name="mailList" type="mailListDict" minOccurs="1"/> 
    </xs:all> 
  </xs:complexType> 
  <xs:complexType name="mailListDict"> 
    <xs:all> 
	<xs:element name="lastUpdate" type="xs:dateTime" minOccurs="1"/> 
	<xs:element name="messageLimit" type="xs:int" minOccurs="1"/> 
	<xs:element name="messageList" type="messageListArray" minOccurs="1"/> 
    </xs:all> 
  </xs:complexType> 
  <xs:complexType name="folderMessagesDict"> 
    <xs:all> 
	<xs:element name="folderName" type="xs:string" minOccurs="1"/> 
	<xs:element name="messageCount" type="xs:int" minOccurs="1"/> 
        <xs:element name="totalCount" type="xs:int" minOccurs="0" maxOccurs="1"/>
	<xs:element name="messages" type="messagesArray" minOccurs="1"/> 
    </xs:all> 
  </xs:complexType> 
  <xs:complexType name="messageElementDict"> 
    <xs:all> 
	<xs:element name="sender" type="xs:string" minOccurs="1"/> 
	<xs:element name="subject" type="xs:string" minOccurs="1"/> 
	<xs:element name="sentOn" type="xs:dateTime" minOccurs="1"/> 
	<xs:element name="seen" type="xs:boolean" minOccurs="1"/> 
	<xs:element name="deleted" type="xs:boolean" minOccurs="1"/> 
	<xs:element name="read" type="xs:boolean" minOccurs="1"/> 
	<xs:element name="hasAttachment" type="xs:boolean" minOccurs="1"/> 
	<xs:element name="hasEmbed" type="xs:boolean" minOccurs="1"/> 
	<xs:element name="classification" type="xs:string" minOccurs="1"/> 
	<xs:element name="messageIconLink" type="xs:string" minOccurs="1"/> 
	<xs:element name="messageLink" type="xs:string" minOccurs="1"/> 
        <xs:element name="digest" type="xs:string" minOccurs="0" maxOccurs="1"/>
    </xs:all> 
  </xs:complexType> 
  <xs:complexType name="messageListArray"> 
    <xs:sequence> 
	  <xs:element name="folderMessages" type="folderMessagesDict" minOccurs="1" maxOccurs="2"/> 
    </xs:sequence> 
  </xs:complexType> 
  <xs:complexType name="messagesArray"> 
    <xs:sequence> 
	  <xs:element name="messageElement" type="messageElementDict" minOccurs="0" maxOccurs="75"/> 
    </xs:sequence> 
  </xs:complexType> 
</xs:schema>

Sample JSON Response Structure

     {
       "response":{

        "statusCode":"",
        "statusText":"",
        "statusDetailCode":"",
        "requestId":"",
        "data":{

            "mailList":{

                "lastUpdate":"",
                "messageLimit":"",
                "messageList":[

                    {

                        "folderName":"",
                        "messageCount":"",
                        "totalCount":"",
                        "messages":[

                            {

                                "sender":"",
                                "subject":"",
                                "sentOn":"",
                                "seen":"",
                                "deleted":"",
                                "read":"",
                                "hasAttachment":"",
                                "hasEmbed":"",
                                "classification":"",
                                "messageIconLink":"",
                                "messageLink":"",
                            }

                        ]

                    }

                ]

            }

        } 

    }}

Error Codes

200 - Success (Ok)

451 - Permission Denied

460 - Missing required parameter

462 - Parameter error

408 - Request Timeout

500 - Generic Server Error

Note: For OpenAuth error codes, consult http://dev.aol.com/openauth_api

Field Descriptions

<dictionary name="mailList"> 
  <datetime key="lastUpdate"> 
      <doc> Indicative of when the message list information was retrieved. /doc> 
  </datetime> 
  <int key="messageLimit"> 
      <doc> Maximum number of messages that can be returned via the getMailList service.</doc>
 </int> 
 <array key="messageList"> 
      <doc> The list of messages per folder.</doc>
<dictionary ref="folderMessages"/> 
  </array> 
</dictionary> 
<dictionary name="folderMessages"> 
  <string key="folderName" required="yes"> 
      <doc> The message folder name.</doc> 
  </string> 
  <int key="messageCount"> 
      <doc> Total number of messages in folder. </doc> 
  </int> <array key="messages"> 
      <doc> The list of messages.</doc> 
<dictionary ref="messageElement"/>
  </array> 
</dictionary> 
<dictionary name="messageElement"> 
    <doc>The individual message.</doc>
  <string key="sender" required="yes"> 
    <doc> The sender name/email id.</doc> 
  </string> 
  <string key="subject" required="yes"> 
    <doc> Message subject.</doc> 
  </string> 
  <datetime key="sentOn" required="yes"> 
    <doc> The date/time when the message was sent.</doc>
  </datetime> 
  <bool key="seen" required="yes">
    <doc> Will be set if the IMAP Seen flag is set(reserved for future use) </doc>
  </bool> 
  <bool key="deleted" required="yes"> 
    <doc> Will be set if the IMAP Deleted flag is set(reserved for future use) </doc> 
  </bool> 
  <bool key="read" required="yes"> 
    <doc>Will be set if the message has been read and then marked as new</doc> 
  </bool> 
  <bool key="hasAttachment" required="yes"> 
    <doc> Whether the message has an attachment. </doc> 
  </bool> 
  <bool key="hasEmbed" required="yes"> 
    <doc> Whether the message has an image. </doc> 
  </bool> 
  <string key="classification" required="yes"> 
    <doc> The type of message. Valid values will be one of: normal,official, voice, priority, billpay, bulk.</doc>
  </string> 
  <string key="messageIconLink" required="no"> 
    <doc> URL to an image file that corresponds to the type of message.</doc> 
  </string> 
  <string key="messageLink" required="no"> 
    <doc> URL to the AOL Webmail product/</doc> 
  </string> 
</dictionary>
Submitted by Developer Network on January 3, 2008 - 10:46am.
»

 

Login | AOL.com | About Us | Site Map | Help
Contact Us | AOL Terms of Service | AOL Privacy Policy
© 2008 AOL LLC. All Rights Reserved.