Whatever message this page gives is out now! Go check it out!

cfpop

Last update:
May 18, 2026

Description

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

Category

Communications tags ,  Internet protocol tags

Syntax

<cfpop 
server = "server name" 
action = "getHeaderOnly|getAll|delete|markRead" 
attachmentPath = "path" 
debug = "yes|no"> 
generateUniqueFilenames = "yes|no" 
maxRows = "number" 
messageNumber = "number" 
name = "query name" 
password = "password" 
port = "port number" 
secure = "yes|no"> 
startRow = "number" 
timeout = "seconds" 
uid = "number" 
delimeter = "delimeter char"
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.

See also

cfftp ,  cfhttp ,  cfldap ,  cfmail ,  cfmailparam ,  SetLocale ;  Sending and Receiving E-Mail  in the Developing ColdFusion Applications

History

ColdFusion 11: New action, markRead is supported. New attribute delimeter.
ColdFusion 10: Added attribute {{secure}}
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.

Attributes

AttributeReq/OptDefaultDescription
server
Required
POP server identifier:
  • A host name, for example, "biff.upperlip.com".
  • An IP address, for example, "192.1.2.225".
action
Optional
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
  • markRead: marks the message as read
attachmentPath
Optional
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.
debug
Optional
no
  • 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.
  • no: does not generate debugging output.
generateUniqueFilenames
Optional
no
  • yes: generate unique filenames for files attached to an e-mail message, to avoid naming conflicts when files are saved.
  • no
maxRows
Optional
Retrieves all available rows
Number of messages to return or delete, starting with the number in startRow. Ignored if messageNumber or uid is specified.
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
Required if action = "getAll" or "getHeaderOnly"
Name for query object that contains the retrieved message information.
password
Optional
Password that corresponds to username.
port
Optional
110
POP port.
secure
Optional
no
if set to yes, enables SSL for pop requests.
startRow
Optional
1
First row number to get or delete. Ignored if messageNumber or uid is specified.
timeout
Optional
60
Maximum time, in seconds, to wait for mail processing.
uid
UID or a comma-separated list of UIDs to get or delete. Invalid UIDs are ignored.
username
Optional
A user name.
delimiterOptional 
The value of the uid attribute can be a comma-separated list of UIDs. If the delimiter attribute is specified, the value of delimiter will be used as a delimiter instead of comma.

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

The attachmentpath attribute

Use the following syntax to specify an in-memory directory in the attachmentpath attribute. In-memory files speed processing of transient data.
ram:///path
The path can include multiple directories, for example ram:///petStore/mail/attachments You must create the directories in the path before you specify the file. For more information on using in-memory files, see Working with in-memory files in  Optimizing ColdFusion applications  in the Developing ColdFusion Applications.

The cfpop query variables

The following table describes the variables that provide information about the query that is returned by cfpop:
Variable namesDescription
queryname.recordCount
Number of records returned by query.
queryname.currentRow
Current row that cfoutput is processing.
queryname.columnList
List of column names in query.

Query message header and body columns

The following table lists the message header and body columns that are returned if action = "getHeaderOnly" or "getAll":
Column namegetHeaderOnly returnsgetAll returns
queryname.date
yes
yes
queryname.from
yes
yes
queryname.messagenumber
yes
yes
queryname.messageid
yes
yes
queryname.replyto
yes
yes
queryname.subject
yes
yes
queryname.cc
yes
yes
queryname.to
yes
yes
queryname.body
no
yes
queryname.textBody
no
yes
queryname.HTMLBody
no
yes
queryname.header
yes
yes
queryname.attachments
no
yes
queryname.attachmentfiles
no
yes
queryname.UID
yes
yes
queryname.cids
no
yes
If the mail message includes a part with a Content-Type of text/plain, the queryname.textBody column contains the part's message content. If the mail message includes a part with a Content-Type of text/HTML, the queryname.HTMLBody column contains the part's message content. If no Content-Type matches these types, the columns are empty. The queryname.Body column always contains the first message body found. The queryname.attachments column contains a tab-separated list of all the attachment names. The queryname.attachmentfiles column contains a tab-separated list of the locations of the attachment files. Use the cffile tag to delete these temporary files when you have processed them. 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:
LocaleHow to create a ColdFusion date/time object from queryname.date
English (US)
Use the  ParseDateTime  function. If you specify the pop-conversion attribute, the function adjusts the date/time object to UTC.
Other
Extract the date part of string; pass it to the  LSParseDateTime  function.
To set the default display format of date, time, number, and currency values, use the  SetLocale  function.
For more information on cfpop, see  Sending and Receiving E-Mail  in the Developing ColdFusion Applications.

Example

<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 structKeyExists(form, "server")>  
<!--- Make sure server, username are not empty. ---> 
<cfif len(trim(form.server)) and len(trim(form.username))>  
<cfpop server = "#form.popserver#" username = "#form.username#" password = "#form.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>  
<p><input type = "Text" name = "popserver"></p>  
<p>Enter your username:</p>  
<p><input type = "Text" name = "username"></p>  
<p>Enter your password:</p>  
<p><input type = "password" name = "pwd"></p>  
<p><input type = "Submit" name = "get message headers"></p>  
</form>

Share this page

Was this page helpful?
We're glad. Tell us how this page helped.
We're sorry. Can you tell us what didn't work for you?
Thank you for your feedback. Your response will help improve this page.

On this page