Click here to close now.


You will be redirected in 30 seconds or close now.

ColdFusion Authors: Yakov Fain, Maureen O'Gara, Nancy Y. Nee, Tad Anderson, Daniel Kaar

Related Topics: ColdFusion

ColdFusion: Article

Use the JavaMail API to Build an IMAP Custom Tag

Use the JavaMail API to Build an IMAP Custom Tag

Don't reinvent the wheel." We've all heard, and perhaps uttered, this maxim many times during our programming careers. ColdFusion MX has introduced new features to help CF developers avoid reinventing the wheel, including tag-based user-defined functions (UDFs) and ColdFusion components (CFCs).

As more CF developers begin to use these features, more code will be available for other developers to download and use. However, code reuse in ColdFusion is not limited to ColdFusion code. Integrating with Java is easier than ever with MX. Since the developer base for Java is large and it has been around much longer than ColdFusion UDFs and CFCs, there is a lot of code already out there that CF developers can use. I discovered this firsthand on a recent project when I didn't think about using existing Java libraries before starting down another path.

This project required me to programmatically access e-mail messages in a subfolder of an e-mail inbox. I couldn't use the CFPOP tag to do this because the protocol implemented by CFPOP - the "Post Office Protocol" - is designed to allow users to download messages from the "inbox" folder only. Another protocol is required to access subfolders - the Internet Message Access Protocol (IMAP).

After discovering that I needed to use IMAP to accomplish my task, I looked for a way to use it with ColdFusion. Unfortunately, since there is no built-in ColdFusion tag that implements IMAP, and I had been looking for an excuse to play around with Java, my first reaction was "Cool! I'll write my own!"

I learned a few IMAP commands and started playing around with the low-level Java networking libraries. Two days and many lines of code later, I had written a marginal IMAP client. Although it mostly worked, it still needed additional functionality and I wasn't at all confident in its stability. I knew there had to be a better way.

JavaMail API
Fortunately, I discovered that there is a much better way - use the JavaMail API. According to Sun's JavaMail Web site (, this API "provides a set of abstract classes that model a mail system" including support for IMAP - the same functionality (plus a lot more) that I had been struggling with for two days. Best of all, since it's included in the J2EE platform, on which ColdFusion MX is built, I didn't have to download anything or make any configuration changes to use it. This was the option I should have considered from the start.

Design Goals
Now that I had found a library, I wanted to make it simple to use from ColdFusion. Since I was already comfortable using the CFPOP tag, I decided to encapsulate some of JavaMail's functionality into a custom tag that, as much as possible, provides the same interface as CFPOP. The tag's full code is shown in the code listing. Listing 1 shows the functions that interact with the API.

Listing 2 shows the tag's main logic. For the sake of brevity, the code shown in the listing includes only one of the actions provided by CFPOP's interface - the "GETHEADERONLY" action. This excludes the "GETALL" action, which provides the ability to view a message's contents and attachments, and the "DELETE" action.

The Code
The JavaMail API consists of a bunch of classes that model a mail system. The highest-level class is the "Session" class. The session class allows you to specify properties like "port" and "timeout." To specify properties, first create and set a "Properties" object. The following sets the protocol to IMAP and the port to 143:

obj_Properties =

Now create the session object and pass in the properties object:

cls_Session =
obj_Session =

The session class also provides a method for getting the "store." The store class abstracts the underlying protocol (in this case IMAP) and provides methods for logging into the mailbox.

obj_Store = createObject("Java",
obj_Store =

Now you are ready to start accessing folders. The only folder that you can access using POP is the "inbox" folder. With IMAP, you can access subfolders below the inbox. The following code accesses and opens the folder "test," which is a subfolder of "inbox":

obj_Folder =

Note that this code opens the folder with read permissions only. This is a good idea if you only want to browse the contents of the folder. If you want to delete, move, or update messages, open the folder with read and write permissions:

The next step is to get a list of messages in the folder. With the JavaMail API, this is done by retrieving an array of "Message" objects.

ar_Messages =

This code returns all messages in the folder. If you only need a subset of the messages, you must pass an array of message numbers to the "getMessages" function. Because I modeled my IMAP tag after the CFPOP tag, I wanted to allow the user to pass a list of message numbers to the tag. This discrepancy was easily remedied by using the built-in "ListToArray" ColdFusion function.

ar_Messages =

Once you have the messages, you are ready to read the message headers using methods of the "Message" object. The following shows how to access the "subject" and "to addresses" of the first message in the folder (which is located at position 1 of the messages array):

// Get the received date
str_Subject =

// Get the to addresses
cls_RecipientType =
ar_To =
lst_ToAddresses =

Note that the "getRecipients" method of the "Message" object returns an array of addresses since an e-mail message can be addressed to more than one person. This is also true when getting the "from", "reply-to", "CC", and "BCC" addresses. Also note the dollar sign ($) syntax used to invoke the "RecipientType" class. RecipientType is an "inner class" of the "Message" class. Although you can access inner classes in Java code by using dot notation (e.g., "Message.RecipientType"), this doesn't work in ColdFusion code.

Now that you have read the messages, the next step is to delete the unwanted ones. To do this, you set the "deleted" flag of the message and then call the folder object's "expunge" method:

cls_Flag =

Where to Go from Here
The code presented here only scratches the surface of the functionality provided by IMAP. Most obviously, it lacks the ability to read message contents and attachments. Another useful feature would allow users to retrieve a listing of subfolders. If you are interested in adding these or other features, check out the JavaMail tutorial at onlineTraining/JavaMail/contents.html and the API specification at javamail/1.3/docs/javadocs/index.html.

With the release of MX, ColdFusion developers have more options for code reuse, including native access to a wide array of predeveloped Java software. Sometimes, especially for developers who don't have extensive Java experience, using existing Java libraries is not always the most obvious option. However, in ColdFusion MX, it can be a very worthwhile option to consider. It certainly is one that I strongly recommend the next time you start a project and think "Cool, I'll just write it myself..."

More Stories By Christian Thompson

Christian Thompson is a certified advanced Macromedia ColdFusion MX developer. He is a senior software engineer for Inserso, a technology consulting firm headquartered in Annandale, VA, where he has specialized in ColdFusion application development for over two years.

Comments (4) View Comments

Share your thoughts on this story.

Add your comment
You must be signed in to add a comment. Sign-in | Register

In accordance with our Comment Policy, we encourage comments that are on topic, relevant and to-the-point. We will remove comments that include profanity, personal attacks, racial slurs, threats of violence, or other inappropriate material that violates our Terms and Conditions, and will block users who make repeated violations. We ask all readers to expect diversity of opinion and to treat one another with dignity and respect.

Most Recent Comments
Christian Thompson 05/27/03 10:53:00 AM EDT

As it is, the tag does not allow you to connect with NNTP servers. With a little configuration (getting and setting up an NNTP provider), though, JavaMail does. Once you got this set up, you would have create a tag similar to CF_IMAP that performs the necessary actions. I have included a link that talks a little about accessing NNTP servers with JavaMail.

Craig Rosenblum 05/26/03 11:17:00 PM EDT

Does this allow us to do nntp reading and posting?

Christian Thompson 05/12/03 02:25:00 PM EDT

According to the documentation, BlueDragon's CFIMAP implements the following actions: list folders, list messages, mark message as read, delete message, move message, delete folder, and move folder. Since the tag presented in this article currently only lists messages, you would need to add the rest of the functions. The good news is that they are all implemented in JavaMail. You would just need to write the CF code to call the functions.

Abraham 05/08/03 12:24:00 PM EDT

Nice article.

I'm planning to write a email app and want IMAP support.

I've been playing with BlueDragon lately, which offers a tag called CFIMAP. Would it take much extra code to get the same functionality?

@ThingsExpo Stories
SYS-CON Events announced today that Luxoft Holding, Inc., a leading provider of software development services and innovative IT solutions, has been named “Bronze Sponsor” of SYS-CON's @ThingsExpo, which will take place on November 3–5, 2015, at the Santa Clara Convention Center in Santa Clara, CA. Luxoft’s software development services consist of core and mission-critical custom software development and support, product engineering and testing, and technology consulting.
Developing software for the Internet of Things (IoT) comes with its own set of challenges. Security, privacy, and unified standards are a few key issues. In addition, each IoT product is comprised of at least three separate application components: the software embedded in the device, the backend big-data service, and the mobile application for the end user's controls. Each component is developed by a different team, using different technologies and practices, and deployed to a different stack/target - this makes the integration of these separate pipelines and the coordination of software upd...
SYS-CON Events announced today that IBM Cloud Data Services has been named “Bronze Sponsor” of SYS-CON's 17th Cloud Expo, which will take place on November 3–5, 2015, at the Santa Clara Convention Center in Santa Clara, CA. IBM Cloud Data Services offers a portfolio of integrated, best-of-breed cloud data services for developers focused on mobile computing and analytics use cases.
In his session at @ThingsExpo, Tony Shan, Chief Architect at CTS, will explore the synergy of Big Data and IoT. First he will take a closer look at the Internet of Things and Big Data individually, in terms of what, which, why, where, when, who, how and how much. Then he will explore the relationship between IoT and Big Data. Specifically, he will drill down to how the 4Vs aspects intersect with IoT: Volume, Variety, Velocity and Value. In turn, Tony will analyze how the key components of IoT influence Big Data: Device, Connectivity, Context, and Intelligence. He will dive deep to the matrix...
When it comes to IoT in the enterprise, namely the commercial building and hospitality markets, a benefit not getting the attention it deserves is energy efficiency, and IoT’s direct impact on a cleaner, greener environment when installed in smart buildings. Until now clean technology was offered piecemeal and led with point solutions that require significant systems integration to orchestrate and deploy. There didn't exist a 'top down' approach that can manage and monitor the way a Smart Building actually breathes - immediately flagging overheating in a closet or over cooling in unoccupied ho...
SYS-CON Events announced today that Cloud Raxak has been named “Media & Session Sponsor” of SYS-CON's 17th Cloud Expo, which will take place on November 3–5, 2015, at the Santa Clara Convention Center in Santa Clara, CA. Raxak Protect automates security compliance across private and public clouds. Using the SaaS tool or managed service, developers can deploy cloud apps quickly, cost-effectively, and without error.
Scott Guthrie's keynote presentation "Journey to the intelligent cloud" is a must view video. This is from AzureCon 2015, September 29, 2015 I have reproduced some screen shots in case you are unable to view this long video for one reason or another. One of the highlights is 3 datacenters coming on line in India.
“The Internet of Things transforms the way organizations leverage machine data and gain insights from it,” noted Splunk’s CTO Snehal Antani, as Splunk announced accelerated momentum in Industrial Data and the IoT. The trend is driven by Splunk’s continued investment in its products and partner ecosystem as well as the creativity of customers and the flexibility to deploy Splunk IoT solutions as software, cloud services or in a hybrid environment. Customers are using Splunk® solutions to collect and correlate data from control systems, sensors, mobile devices and IT systems for a variety of Ind...
SYS-CON Events announced today that ProfitBricks, the provider of painless cloud infrastructure, will exhibit at SYS-CON's 17th International Cloud Expo®, which will take place on November 3–5, 2015, at the Santa Clara Convention Center in Santa Clara, CA. ProfitBricks is the IaaS provider that offers a painless cloud experience for all IT users, with no learning curve. ProfitBricks boasts flexible cloud servers and networking, an integrated Data Center Designer tool for visual control over the cloud and the best price/performance value available. ProfitBricks was named one of the coolest Clo...
You have your devices and your data, but what about the rest of your Internet of Things story? Two popular classes of technologies that nicely handle the Big Data analytics for Internet of Things are Apache Hadoop and NoSQL. Hadoop is designed for parallelizing analytical work across many servers and is ideal for the massive data volumes you create with IoT devices. NoSQL databases such as Apache HBase are ideal for storing and retrieving IoT data as “time series data.”
Clearly the way forward is to move to cloud be it bare metal, VMs or containers. One aspect of the current public clouds that is slowing this cloud migration is cloud lock-in. Every cloud vendor is trying to make it very difficult to move out once a customer has chosen their cloud. In his session at 17th Cloud Expo, Naveen Nimmu, CEO of Clouber, Inc., will advocate that making the inter-cloud migration as simple as changing airlines would help the entire industry to quickly adopt the cloud without worrying about any lock-in fears. In fact by having standard APIs for IaaS would help PaaS expl...
Organizations already struggle with the simple collection of data resulting from the proliferation of IoT, lacking the right infrastructure to manage it. They can't only rely on the cloud to collect and utilize this data because many applications still require dedicated infrastructure for security, redundancy, performance, etc. In his session at 17th Cloud Expo, Emil Sayegh, CEO of Codero Hosting, will discuss how in order to resolve the inherent issues, companies need to combine dedicated and cloud solutions through hybrid hosting – a sustainable solution for the data required to manage I...
Apps and devices shouldn't stop working when there's limited or no network connectivity. Learn how to bring data stored in a cloud database to the edge of the network (and back again) whenever an Internet connection is available. In his session at 17th Cloud Expo, Bradley Holt, Developer Advocate at IBM Cloud Data Services, will demonstrate techniques for replicating cloud databases with devices in order to build offline-first mobile or Internet of Things (IoT) apps that can provide a better, faster user experience, both offline and online. The focus of this talk will be on IBM Cloudant, Apa...
Mobile messaging has been a popular communication channel for more than 20 years. Finnish engineer Matti Makkonen invented the idea for SMS (Short Message Service) in 1984, making his vision a reality on December 3, 1992 by sending the first message ("Happy Christmas") from a PC to a cell phone. Since then, the technology has evolved immensely, from both a technology standpoint, and in our everyday uses for it. Originally used for person-to-person (P2P) communication, i.e., Sally sends a text message to Betty – mobile messaging now offers tremendous value to businesses for customer and empl...
As more and more data is generated from a variety of connected devices, the need to get insights from this data and predict future behavior and trends is increasingly essential for businesses. Real-time stream processing is needed in a variety of different industries such as Manufacturing, Oil and Gas, Automobile, Finance, Online Retail, Smart Grids, and Healthcare. Azure Stream Analytics is a fully managed distributed stream computation service that provides low latency, scalable processing of streaming data in the cloud with an enterprise grade SLA. It features built-in integration with Azur...
SYS-CON Events announced today that HPM Networks will exhibit at the 17th International Cloud Expo®, which will take place on November 3–5, 2015, at the Santa Clara Convention Center in Santa Clara, CA. For 20 years, HPM Networks has been integrating technology solutions that solve complex business challenges. HPM Networks has designed solutions for both SMB and enterprise customers throughout the San Francisco Bay Area.
The enterprise is being consumerized, and the consumer is being enterprised. Moore's Law does not matter anymore, the future belongs to business virtualization powered by invisible service architecture, powered by hyperscale and hyperconvergence, and facilitated by vertical streaming and horizontal scaling and consolidation. Both buyers and sellers want instant results, and from paperwork to paperless to mindless is the ultimate goal for any seamless transaction. The sweetest sweet spot in innovation is automation. The most painful pain point for any business is the mismatch between supplies a...
The broad selection of hardware, the rapid evolution of operating systems and the time-to-market for mobile apps has been so rapid that new challenges for developers and engineers arise every day. Security, testing, hosting, and other metrics have to be considered through the process. In his session at Big Data Expo, Walter Maguire, Chief Field Technologist, HP Big Data Group, at Hewlett-Packard, will discuss the challenges faced by developers and a composite Big Data applications builder, focusing on how to help solve the problems that developers are continuously battling.
As enterprises capture more and more data of all types – structured, semi-structured, and unstructured – data discovery requirements for business intelligence (BI), Big Data, and predictive analytics initiatives grow more complex. A company’s ability to become data-driven and compete on analytics depends on the speed with which it can provision their analytics applications with all relevant information. The task of finding data has traditionally resided with IT, but now organizations increasingly turn towards data source discovery tools to find the right data, in context, for business users, d...
SYS-CON Events announced today that MobiDev, a software development company, will exhibit at the 17th International Cloud Expo®, which will take place November 3-5, 2015, at the Santa Clara Convention Center in Santa Clara, CA. MobiDev is a software development company with representative offices in Atlanta (US), Sheffield (UK) and Würzburg (Germany); and development centers in Ukraine. Since 2009 it has grown from a small group of passionate engineers and business managers to a full-scale mobile software company with over 150 developers, designers, quality assurance engineers, project manage...