cfpop

Description

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

History

ColdFusion MX 7.01: Added cids query variable. ColdFusion MX 6.1: Added support for multipart mail messages with Text and HTML parts. Changed the attachment name separator: the TAB character is now the separator between attachment names in the attachments and attachmentfiles query fields if a message has multiple attachments. This behavior is identical to ColdFusion 5 and earlier versions. ColdFusion MX: Changed the attachment name separator: the comma separates names in the attachments and attachmentfiles query fields if a message has multiple attachments.

Syntax

<cfpop  
    server = "server name" 
    action = "getHeaderOnly|getAll|delete" 
    attachmentPath = "path" 
    debug = "yes|no"> 
    generateUniqueFilenames = "yes|no" 
    maxRows = "number" 
    messageNumber = "number" 
    name = "query name" 
    password = "password" 
    port = "port number" 
    startRow = "number" 
    timeout = "seconds" 
    uid = "number" 
    username = "user name">

Note: You can specify this tag’s attributes in an attributeCollection attribute whose value is a structure. Specify the structure name in the attributeCollection attribute and use the tag’s attribute names as structure keys.

Attributes

Attribute	Description	Required	Default
action	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	Optional	getHeaderOnly
attachmentPath	If action="getAll", specifies a directory in which to save any attachments. If the directory does not exist, ColdFusion creates it. If you omit this attribute, ColdFusion does not save any attachments. If you specify a relative path, the path root is the ColdFusion temporary directory, which is returned by the GetTempDirectory function.	Optional
debug	yes: sends debugging output to standard output. By default, if the console window is unavailable on server configurations, ColdFusion sends output to cf_root/runtime/logs/coldfusion-out.log. On J2EE configurations, with JRun, the default location is jrun_home/logs/servername-out.log. Caution: If you set this option to Yes, ColdFusion writes detailed debugging information to the log, including all retrieved message contents, and can generate large logs quickly. no: does not generate debugging output.	Optional	no
generateUniqueFilenames	yes: generate unique filenames for files attached to an e-mail message, to avoid naming conflicts when files are saved. no	Optional	no
maxRows	Number of messages to return or delete, starting with the number in startRow. Ignored if messageNumber or uid is specified.	Optional	Retrieves all available rows
messageNumber	Message number or comma-separated list of message numbers to get or delete. Invalid message numbers are ignored. Ignored if uid is specified.
name	Name for query object that contains the retrieved message information.	Required if action="getAll" or "getHeaderOnly"
password	Password that corresponds to username.	Optional
port	POP port.	Optional	110
server	POP server identifier: A host name, for example, "biff.upperlip.com". An IP address, for example, "192.1.2.225".	Required
startRow	First row number to get or delete. Ignored if messageNumber or uid is specified.	Optional	1
timeout	Maximum time, in seconds, to wait for mail processing.	Optional	60
uid	UID or a comma-separated list of UIDs to get or delete. Invalid UIDs are ignored.
username	A user name.	Optional

Usage

The cfpop tag retrieves one or more mail messages from a POP server and populates a ColdFusion query object with the resulting messages, one message per row. Alternatively, it deletes one or more messages from the POP server.
Note: When the cfpop tag encounters malformed mail messages, it does not generate errors; instead, it returns empty fields.
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 long, and therefore take longer to process.

Example

<!--- This view-only example shows the use of cfpop. ---> 
<h3>cfpop Example</h3> 
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. 
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 = "#form.popserver# " username = #form.username# password = #form.pwd# 
        action = "getHeaderOnly" name = "GetHeaders "> 
        <h3>Message Headers in Your Inbox</h3> 
        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"> 
    Enter your mail server:</p> 
    <input type = "Text" name = "popserver"></p> 
    Enter your username:</p> 
    <input type = "Text" name = "username"></p> 
    Enter your password:</p> 
    <input type = "password" name = "pwd"></p> 
    <input type = "Submit" name = "get message headers"></p> 
</form>  
--->

cfmldocs