Adobe ColdFusion 8

Receiving e-mail messages

You create ColdFusion pages to access a Post Office Protocol (POP) server to retrieve e-mail message information. ColdFusion can then display the messages (or just header information), write information to a database, or perform other actions.

The cfpop tag lets you add Internet mail client features and e-mail consolidation to applications. Although a conventional mail client provides an adequate interface for personal mail, there are many cases in which an alternative interface to some mailboxes is advantageous. You use cfpop to develop targeted mail clients to suit the specific needs of a wide range of applications. The cfpop tag does not work with the other major e-mail protocol, Internet Mail Access Protocol (IMAP).

Here are three instances in which implementing POP mail makes sense:

  • If your site has generic mailboxes that are read by more than one person (sales@yourcompany.com), it can be more efficient to construct a ColdFusion mail front end to supplement individual user mail clients.
  • In many applications, you can automate mail processing when the mail is formatted to serve a particular purpose; for example, when subscribing to a list server.
  • If you want to save e-mail messages to a database.

Using cfpop with your POP server is like running a query on your mailbox contents. You set its action attribute to retrieve either headers (using the GetHeaderOnly value) or entire messages (using the GetAll value) and assign it a name value. You use the name to refer to the record set that cfpop returns, for example, when using the cfoutput tag. To access a POP server, you also must define the server, username, and password attributes.

Note: If the cfpop tag encounters an error, such as an improperly formatted email message, when retrieving messages, it tries to ignore the error; it returns empty fields in the result structure and retrieves any available messages.

For more information on the cfpop tag's syntax and variables, see the CFML Reference.

Using the cfpop tag

Use the following steps to add POP mail to your application.

Implement the cfpop tag in your application

  1. Choose the mailboxes to access within your ColdFusion application.
  2. Determine which mail message components you must process: message header, message body, attachments, and so on.
  3. Decide whether you must store the retrieved messages in a database.
  4. Decide whether you must delete messages from the POP server after you retrieve them.
  5. Incorporate the cfpop tag in your application and create a user interface for accessing a mailbox.
  6. Build an application page to handle the output. Retrieved messages can include characters that do not display properly in the browser.

You use the cfoutput tag with the HTMLCodeFormat and HTMLEditFormat functions to control output to the browser. These functions convert characters with special meanings in HTML, such as the less than (<), greater than (>), and ampersand (&) symbols, into HTML-escaped characters, such as &lt;, &gt;, and &amp;. The HTMLCodeFormat tag also surrounds the text in a pre tag block.

The cfpop query variables

Like any ColdFusion query, each cfpop query returns variables that provide information about the record:

RecordCount: The total number of records returned by the query.

ColumnList: A list of the headings of the columns that are returned by the query

CurrentRow: The current row of the query being processed by cfoutput or cfloop in a query-driven loop.

The query includes one variable that is not returned by the cfquery tag: the UID variable contains the unique identifier of the e-mail message file.

You can reference these properties in a cfoutput tag by prefixing the query variable with the query name in the name attribute of cfpop:

<cfoutput>
This operation returned #Sample.RecordCount# messages.
</cfoutput>