CFPOP  
Description

Retrieves and deletes e-mail messages from a POP mail server.

 
Category

Forms tags, Internet Protocol tags

 
Syntax
    <cfpop 
   server = "servername"
   port = "port_number"
   username = "username"
   password = "password"
   action = "action"
   name = "queryname"
   messageNumber = "number"
   uid = "number" 
   attachmentPath = "path"
   timeout = "seconds"
   maxRows = "number"
   startRow = "number"
   generateUniqueFilenames = "boolean">

  
 
See also

cfftp, cfhttp, cfldap, cfmail, cfmailparam, SetLocale

 
Usage
Note: To optimize performance, two retrieve options are available. Message header information is typically short, and therefore quick to transfer. Message text and attachments can be very long, and therefore take longer to process.
 
cfpop query variables

The following table describes the query variables that are returned by cfpop:

Variable names Description

queryname.recordCount

Number of records returned by query

queryname.currentRow

Current row that cfoutput is processing

queryname.columnList

List of column names in query

queryname.UID

Unique identifier for the email message file

 
Message header and body columns

The following table lists the message header and body columns that are returned if action = "getHeaderOnly" or "getAll":

Column Name getHeaderOnly returns getAll returns

queryname.date

yes

yes

queryname.from

yes

yes

queryname.messagenumber

yes

yes

queryname.replyto

yes

yes

queryname.subject

yes

yes

queryname.cc

yes

yes

queryname.to

yes

yes

queryname.body

not available

yes

queryname.header

not available

yes

queryname.attachments

not available

yes

queryname.attachmentfiles

not available

yes

To create a ColdFusion date/time object from the date-time string that is extracted from a mail message in the queryname.date column, use the following table:

Locale How to create a ColdFusion date/time object from queryname.date

English (US)

Use the ParseDateTime function, which converts a date-time value to UTC

Other

Extract the date part of string; pass it to the LSParseDateTime function

Note: To set the default display format of date, time, number, and currency values, use the SetLocale function.

For more information on cfpop, see Developing ColdFusion MX Applications with CFML.

 
Example
<!--- This view-only example shows the use of cfpop --->
<h3>cfpop Example</h3>
<p>cfpop lets you retrieve and manipulate mail in a POP3 mailbox. 
This view-only example shows how to create one feature of 
a mail client, to display the mail headers in a POP3 mailbox.
<p>To execute this, un-comment this code and run with a mail-enabled CF Server.
<!--- 
<cfif IsDefined("form.server ")>
   <!--- make sure server, username are not empty --->
   <cfif form.server is not "" and form.username is not "">
      <cfpop server = "#server# " username = #UserName# password = #pwd#
      action = "GETHEADERONLY " name = "GetHeaders ">
      <h3>Message Headers in Your Inbox</h3>
      <p>Number of Records: 
      <cfoutput>#GetHeaders.recordCount#</cfoutput></p>
      <ul>
         <cfoutput query = "GetHeaders">
         <li>Row: #currentRow#: From: #From# -- Subject: #Subject#
         </cfoutput>
      </ul>
   </cfif>
</cfif>

<form action = "cfpop.cfm " method = "post">
   <p>Enter your mail server:
   <p><input type = "Text" name = "server">
   <p>Enter your username:
   <p><input type = "Text" name = "username">
   <p>Enter your password:
   <p><input type = "password" name = "pwd">
   <input type = "Submit" name = "get message headers">
</form> 
--->
SERVER  
  Required
 

POP server identifier:

  • A host name; for example, "biff.upperlip.com"
  • An IP address; for example, "192.1.2.225"
PORT  
  Optional
 
Default value: "110"

POP port

USERNAME  
  Optional
 
Default value: "Anonymous"
  • A user name
  • "Anonymous"
PASSWORD  
  Optional
 

Password that corresponds to username.

ACTION  
  Optional
 
Default value: "getHeaderOnly"
  • getHeaderOnly: returns message header information only
  • getAll: returns message header information, message text, and attachments if attachmentPath is specified
  • delete: deletes messages on POP server
NAME  
  Required if action = "getAll" or "getHeaderOnly"
 

Name for index query.

MESSAGENUMBER  
  If action = "delete", this attribute, or uid, is required
 

Message number or comma-delimited list of message numbers to get. Applies to action ="getAll" and "getHeaderOnly". For these actions, if it is omitted, all messages are returned. Invalid message numbers are ignored.

UID  
  If action = "delete", this attribute, or messageNumber, is required
 

UID or a comma-delimited list of UIDs to get. Applies to action = "getHeaderOnly" and action = "getAll". For these actions, if it is omitted, all messages are returned. Invalid UIDs are ignored.

ATTACHMENTPATH  
  Optional
 

If action = "getAll", allows attachments to be written to directory. If this value is invalid, no attachment files are written to server.

TIMEOUT  
  Optional
 
Default value: "60"

Maximum time, in seconds, to wait for mail processing.

MAXROWS  
  Optional
 
Default value: "999999"

Number of messages to return, starting with the number in startRow. If messageNumber is specified, this attribute is ignored.

STARTROW  
  Optional
 
Default value: "1"

First row number to get. If messageNumber is specified, this attribute is ignored.

GENERATEUNIQUEFILENAMES  
  Optional
 
Default value: "No"
  • Yes: Generate unique filenames for files attached to an e-mail message, to avoid naming conflicts when files are saved
  • No