Adobe ColdFusion 8

Handling POP mail

This section describes how to specify the message or messages that you want to get (or get information about) and provides an example of each of the following uses of POP mail:

Specifying the message or messages

For all cfpop actions, you can tel the tag to perform the action on all messages, or to do it on selected messages. To operate on all messages, for example to get all message headers, do not specify a messageNumber or UID attribute. To operate on specific messages, for example, to delete three selected messages, specify a messageNumber or UID attribute with a comma-delimited list of messages to act on.

Retrieving message headers

To retrieve message headers without getting the messages, specify action="GetHeaderOnly" in the cfpop tag. Whether you use cfpop to retrieve the header or the entire message, ColdFusion returns a query object that contains one row for each message in the specified mailbox. you specify the query object name in the cfpop tag name attribute. The query has the following fields:

  • date
  • from
  • header (A string with all the mail header fields, including those that have separate fields in the query object)
  • messageNumber (The sequential number of the message in the POP server; identical to the row number of the entry in the query object)
  • messageID (The mail header Message-ID field)
  • replyTo
  • subject
  • cc
  • to
  • UID (The mail header X-UID field)

The cfpop tag with the getHeaderOnly attribute retrieves any file attachments if you specify an attachmentPath attribute; otherwise, it does not get the attachments, and the attachmentfiles column contains empty strings.

Retrieve only the message header

  1. Create a ColdFusion page with the following content:
    <html>
<head>
<title>POP Mail Message Header Example</title>
</head>

<body>
<h2>This example retrieves message header information:</h2>

<cfpop server="mail.company.com"
    username=#myusername#
    password=#mypassword#
    action="GetHeaderOnly"
    name="Sample">

<cfoutput query="Sample">
    MessageNumber: #HTMLEditFormat(Sample.messageNumber)# <br>
    To: #HTMLEditFormat(Sample.to)# <br>
    From: #HTMLEditFormat(Sample.from)# <br>
    Subject: #HTMLEditFormat(Sample.subject)# <br>
    Date: #HTMLEditFormat(Sample.date)#<br>
     Cc: #HTMLEditFormat(Sample.cc)# <br>
    ReplyTo: #HTMLEditFormat(Sample.replyTo)# <br><br>
</cfoutput>

</body>
</html>

  2. Edit the following lines so that they refer to valid values for your POP mail server, user name, and password:
    <cfpop server="mail.company.com"
    username=#myusername#
	password=#mypassword#

  3. Save the file as header_only.cfm in the myapps directory under your web_root and view it in your web browser:

    This code retrieves the message headers and stores them in a cfpop record set called Sample. For more information about working with record set data, see Using Query of Queries.

The HTMLCodeFormat function replaces characters that have meaning in HTML, such as the less than (<) and greater than (>) signs that can surround detailed e-mail address information, with escaped characters such as &lt; and &gt;.

In addition, you can process the date returned by cfpop with the ParseDateTime function, which accepts an argument for converting POP date/time objects into a CFML date-time object.

You can reference any of these columns in a cfoutput tag, as the following example shows:

<cfoutput>
    #ParseDateTime(queryname.date, "POP")#
    #HTMLCodeFormat(queryname.from)#
    #HTMLCodeFormat(queryname.messageNumber)#
</cfoutput>

Retrieving messages

When you use the cfpop tag with action="GetAll", ColdFusion returns the same columns as with getheaderonly, plus the following additional columns:

  • attachments (A tab-delimited list of attachment filenames)
  • attachmentfiles (A tab-delimited list of paths to the attachment files retrieved to the local server, if any. You get the files only if you specify an attachmentpath attribute.)
  • body
  • htmlbody
  • textbody

If the message is multipart, the htmlbody and textbody fields contain the contents of the HTML and plain text parts, and the body field has the first part in the message. If the message has only one part, the body contains the message, and either the htmlbody or textbody field, depending on the message type, also has a copy of the message.

Retrieve entire messages

  1. Create a ColdFusion page with the following content:
    <html>
<head><title>POP Mail Message Body Example</title></head>

<body>
<h2>This example adds retrieval of the message body:</h2>
<cfpop server="mail.company.com"
    username=#myusername#
    password=#mypassword#
    action="GetAll"
    name="Sample">

<cfoutput query="Sample">
    MessageNumber: #HTMLEditFormat(Sample.messageNumber)# <br>
    To: #Sample.to# <br>
    From: #HTMLEditFormat(Sample.from)# <br>
    Subject: #HTMLEditFormat(Sample.subject)# <br>
    Date: #HTMLEditFormat(Sample.date)#<br>
    Cc: #HTMLEditFormat(Sample.cc)# <br>
    ReplyTo: #HTMLEditFormat(Sample.replyTo)# <br>
    <br>
    Body:<br>
    #Sample.body#<br>
    <br>
    Header:<br>
    #HTMLCodeFormat(Sample.header)#<br>
    <hr>
    </cfoutput>

</body>


</html>
  1. Edit the following lines so that they refer to valid values for your POP mail server, user name, and password:
    <cfpop server="mail.company.com"
    username=#myusername#
	password=#mypassword#

  2. Save the file as header_body.cfm in the myapps directory under your web_root and view it in your web browser:

This example does not use a CFML function to encode the body contents. As a result, the browser displays the formatted message as you would normally see it in a mail program that supports HTML messages.

Retrieving messages and attachments

When you use the cfpop tag with an attachmentpath attribute to specify the directory in which to store attachments, ColdFusion retrieves any attachment files from the POP server and saves them in the specified directory. The cfpop tag fills the attachmentfiles field with a tab-separated list of the locations of the attachment files. Use the cffile tag to delete these temporary files when they are no longer needed. ColdFusion creates the directory if it does not exist. (ColdFusion must have the appropriate rights on the system to create the directory.)

If a message has no attachments, the attachments and attachmentfiles columns contain empty strings.

Note: CFML does not provide a way to change the name of a mail attachment returned by cfpop before it tries to save the file. If the attachment name is invalid for the file system on which ColdFusion is running, the attachment cannot be saved.

Retrieve all parts of a message, including attachments

  1. Create a ColdFusion page with the following content:
    <html>
<head>
<title>POP Mail Message Attachment Example</title>
</head>

<body>
<h2>This example retrieves message header,
body, and all attachments:</h2>

<cfpop server="mail.company.com"
    username=#myusername#
    password=#mypassword#
    action="GetAll"
    attachmentpath="c:\temp\attachments"
    name="Sample">

<cfoutput query="Sample">
    MessageNumber: #HTMLEditFormat(Sample.MessageNumber)# <br>
    To: #HTMLEditFormat(Sample.to)# <br>
    From: #HTMLEditFormat(Sample.from)# <br>
    Subject: #HTMLEditFormat(Sample.subject)# <br>
    Date: #HTMLEditFormat(Sample.date)# <br>
    Cc: #HTMLEditFormat(Sample.cc)# <br>
    ReplyTo: #HTMLEditFormat(Sample.ReplyTo)# <br>
    Attachments: #HTMLEditFormat(Sample.Attachments)# <br>
    Attachment Files: #HTMLEditFormat(Sample.AttachmentFiles)# <br>
    <br>
    Body:<br>
    #Sample.body# <br>
    <br>
    Header:<br>
    HTMLCodeFormat(Sample.header)# <br>
    <hr>
</cfoutput>

</body>
</html>

  2. Edit the following lines so that they refer to valid values for your POP mail server, user name, and password:
    <cfpop server="mail.company.com"
    username=#myusername#
	password=#mypassword#

  3. Save the file as header_body_att.cfm in the myapps directory under your web_root and view it in your web browser:

Note: To avoid duplicate filenames when saving attachments, set the generateUniqueFilenames attribute of cfpop to Yes.

Deleting messages

Using the cfpop tag to delete a message permanently removes it from the server. By default, retrieved messages remain on the POP mail server. To delete the messages, set the action attribute of the cfpop tag to Delete. Use the messagenumber attribute to specify the messages to delete; omit the attribute to delete all the user's messages from the server.

Note: Message numbers are reassigned at the end of every POP mail server communication that contains a delete action. For example, if you retrieve four messages from a POP mail server, the server returns the message numbers 1,2,3,4. If you delete messages 1 and 2 with a single cfpop tag, messages 3 and 4 are assigned message numbers 1 and 2, respectively.

Delete messages

  1. Create a ColdFusion page with the following content:
    <html>
<head>
<title>POP Mail Message Delete Example</title>
</head>

<body>
<h2>This example deletes messages:</h2>

<cfpop server="mail.company.com"
    username=#username#
    password=#password#
    action="Delete"
    messagenumber="1,2,3">

</body>
</html>

  2. Edit the following lines so that they refer to valid values for your POP mail server, user name, and password:
    <cfpop server="mail.company.com"
    username=#username#
	password=#password#

  3. Save the file as message_delete.cfm in the myapps directory under your web_root and view the file in your web browser.
  4. Run the header_only.cfm page that you created to confirm that the messages have been deleted.

Important: When you view this page in your web browser, ColdFusion immediately deletes the messages from the POP server.