Home › Blogs › bricemason's blog ›

OpenMail - New Mail List Service

Enable the Subscriptions block here!

Last time I showed you how to interact with the OpenMail API's mail count service using a ColdFusion proxy and Ext JS front end. Today we'll take a look at the new mail list service, a method used to obtain more detailed information about new mail that pops into your AOL mail.

As we did last time, we'll develop a proxy using ColdFusion which will serve as a remote data store to an Ext JS front end. The proxy will simplify the data feed to the front end as well as perform some minor data conversion. Since interaction with this service requires an OpenAuth token, we'll need to prepare our application as follows: 

<cfset aolDevId = "someAOLDevId" />
<cfset succUrl  = "http://localhost:8501/openmail/" />

<cfset obj_openAuth = CreateObject( "component", "AOL.OpenAuth" ).init( aolDevId, succUrl ) />

<cfif isDefined( "url.token_a" )>

    <cfset CreateObject( "component", "MailListRemoteFacade" ).getNewMailList( url.token_a, 
          aolDevId, succUrl ) />
    
<cfelse>
    <cfset obj_openAuth.login() />
</cfif>

We're using the AOL.OpenAuth ColdFusion component (CFC) to handle the authentication. After creating a new component instance, we can evaluate whether we've been authenticated or not by checking for the url.token_a variable. If it's there, we're all set to continue. Otherwise, the login method of the AOL.OpenAuth cfc is invoked which will prompt you for the proper credentials.

Assuming authentication worked as expected, the MailListRemoteFacade component's getNewMailList method is called which will output a minimized data set of information obtained from the OpenMail service. The full source of this component is shown below: 

<cfcomponent displayname="MailListRemoteFacade" output="false">

	<!--- OpenMail new mail list service address --->
	<cfset variables.mailListService = "http://api.mail.aol.com/mail/newMailList" />

	<cffunction name="getNewMailList" access="remote" output="yes" returntype="void">
    	<cfargument name="authToken" type="string" required="yes" />
        <cfargument name="devId"     type="string" required="yes" />
        <cfargument name="referer"   type="string" required="yes" />
        
        <!--- set up local scope --->
        <cfset var local = StructNew() />
    	
        <!--- request for new mail listing, hard coded for the inbox and
			  to return a total message count --->
        <cfhttp url="#variables.mailListService#" method="get">
            <cfhttpparam type="url" name="f"         value="json" />
            <cfhttpparam type="url" name="a"         value="#arguments.authToken#" />
            <cfhttpparam type="url" name="devId"     value="#arguments.devId#" />
            <cfhttpparam type="url" name="referer"   value="#arguments.referer#" />
            <cfhttpparam type="url" name="folder"    value="inbox" />
            <cfhttpparam type="url" name="showCount" value="yes" />
        </cfhttp>
        
        <!--- convert to native cf data structure --->
        <cfset local.st_response = deserializeJson( cfhttp.FileContent ) />
        
        <cfset local.st_minResponse = StructNew() />
        <cfset StructInsert( local.st_minResponse, "messages", ArrayNew(1) ) />
        <cfset StructInsert( local.st_minResponse, "totalCount",
 local.st_response.response.data.mailList.messageList[1].totalCount ) />
        
        <!--- shortcut to the messages --->
        <cfset local.arr_messages = local.st_response.response.data.mailList.messageList[1].messages />
        <cfloop from="1" to="#ArrayLen( local.arr_messages )#" index="local.i">
        	<!--- define a temporary structure, absract the bits we want to keep, tack on 
				  to the 'messages' array --->
        	<cfset local.st_tmp = StructNew() />
            <cfset StructInsert( local.st_tmp, "sender", 
local.arr_messages[local.i].sender ) />
            <cfset StructInsert( local.st_tmp, "messageIconLink",
 local.arr_messages[local.i].messageIconLink ) />
            <cfset StructInsert( local.st_tmp, "messageLink", 
local.arr_messages[local.i].messageLink ) />
            <cfset StructInsert( local.st_tmp, "sentOn", parseISODate( 
local.arr_messages[ local.i ].sentOn ) ) />
            <cfset StructInsert( local.st_tmp, "subject", 
local.arr_messages[local.i].subject ) />
            <cfset ArrayAppend( local.st_minResponse.messages, local.st_tmp ) />
        </cfloop>
    
    	<!--- convert our minimum response to JSON and output --->
    	<cfoutput>#serializeJson( local.st_minResponse )#</cfoutput>
    
    	<cfreturn />
    </cffunction>
    
    <cffunction name="parseISODate" access="private" output="yes" returntype="string">
    	<cfargument name="isoDate" type="string" required="yes" />
    
    	<cfset var local        = StructNew() />
    	<cfset local.re_isoDate = "^(.+)T(.+)[-\+]" />
        <cfset local.st_match   = REFind( local.re_isoDate, arguments.isoDate, 1, "true" ) />
        
        <cfif ArrayLen( local.st_match.len ) eq 3>
        	<cfreturn DateFormat( mid( arguments.isoDate,
 local.st_match.pos[2], local.st_match.len[2] ), "mm/dd/yyyy" ) & " " &
            		  TimeFormat( mid( arguments.isoDate, local.st_match.pos[3],
 local.st_match.len[3] ), "hh:mm:ss tt" ) />
        </cfif>
        
        <cfreturn arguments.isoDate />
    </cffunction>

</cfcomponent>

The MailListRemoteFacade performs a simple HTTP call to the OpenMail service to obtain the new mail list data for a particular account. In addition to the required parameters, this component takes advantage of some other added features you can use such as specifying a particular folder (in this case the inbox) as well as including the total count of new messages in the response. Once data is returned, it's converted to a native ColdFusion data structure and processed down to just the bits we want to keep for our Ext JS front end. A private helper method was also included to parse out the ISO date format returned for date fields in the response. Finally we serialize the data to JSON and output our custom response. Check back this Friday for a demonstration on the development of the Ext JS front end to this service.

» Submitted by bricemason on January 22, 2008 - 11:52am.