User Guide Cancel

cfpop

Last updated on May 30, 2024 | Also applies to ColdFusion

ColdFusion

Open app

CFML Reference User Guide
ColdFusion functions
ColdFusion Tags
1. ColdFusion tag summary
2. ColdFusion tags by category
  1. Application framework tags
    1. cfapplication
    2. cfassociate
    3. cferror
    4. cfimport
    5. cfinterface
    6. cflock
    7. cfscript
    8. cfthread
  2. Communications tags
  3. Database manipulation tags
  4. Data output tags
    1. cfchart
    2. cfchartdata
    3. cfchartseries
    4. cfcol
    5. cfcontent
    6. cfdocument
    7. cfdocumentitem
    8. cfdocumentsection
    9. cfflush
    10. cfheader
    11. cflog
    12. cfoutput
    13. cfpresentation
    14. cfpresentationslide
    15. cfpresenter
    16. cfprocessingdirective
    17. cfprint
    18. cfreport
    19. cfreportparam
    20. cfsilent
    21. cftable
  5. Debugging tags
    1. cfdump
    2. cftimer
    3. cftrace
  6. Exception handling tags
    1. cfcatch
    2. cferror
    3. cffinally
    4. cfrethrow
    5. cfthrow
    6. cftry
  7. Extensibility tags
    1. cfchart
    2. cfchartdata
    3. cfchartseries
    4. cfcollection
    5. cfcomponent
    6. cfexecute
    7. cfftp
    8. function
    9. cfindex
    10. cfinterface
    11. cfinvoke
    12. cfinvokeargument
    13. cfobject
    14. cfproperty
    15. cfreport
    16. cfreportparam
    17. cfreturn
    18. cfsearch
    19. cfsharepoint
    20. cfspreadsheet
    21. cfwddx
    22. cfxml
  8. File management tags
    1. cfdirectory
    2. cffile
    3. cffileupload
    4. cfftp
    5. cfzip
    6. cfzipparam
  9. Flow-control tags
    1. cfabort
    2. cfbreak
    3. cfcase
    4. cfcontinue
    5. cfdefaultcase
    6. cfelse
    7. cfelseif
    8. cfexecute
    9. cfexit
    10. cfif
    11. cfinclude
    12. cflocation
    13. cfloop
    14. cfrethrow
    15. cfswitch
    16. cfthrow
    17. cftry
  10. Forms tags
    1. cfapplet
    2. cfcalendar
    3. cffileupload
    4. cfform
    5. cfformgroup
    6. cfformitem
    7. cfgrid
    8. cfgridcolumn
    9. cfgridrow
    10. cfgridupdate
    11. cfinput
    12. cfpdf
    13. cfpdfform
    14. cfpdfformparam
    15. cfpdfparam
    16. cfpdfsubform
    17. cfselect
    18. cfslider
    19. cftextarea
    20. cftree
    21. cftreeitem
  11. Internet Protocol tags
    1. cfajaximport
    2. cfajaxproxy
    3. cfftp
    4. cffeed
    5. cfimap
    6. cfhttp
    7. cfhttpparam
    8. cfldap
    9. cfmail
    10. cfmailparam
    11. cfmailpart
    12. cfpop
    13. cfsprydataset
  12. Page processing tags
    1. cfcache
    2. cfcontent
    3. cfflush
    4. cfheader
    5. cfhtmlhead
    6. cfinclude
    7. cfprocessingdirective
    8. cfsetting
    9. cfsilent
  13. Security tags
  14. Variable manipulation tags
    1. cfcookie
    2. cfdump
    3. cfparam
    4. cfregistry
    5. cfsavecontent
    6. cfschedule
    7. cfset
    8. cfsetting
  15. Other tags
    1. cfimage
    2. cflog
    3. cfregistry
3. Tags a-b
4. Tags c
  1. cfcache
  2. cfcalendar
  3. cfcase
  4. cfcatch
  5. cfchart
  6. cfchartdata
  7. cfchartseries
  8. cfclient
  9. cfclientsettings
  10. cfcol
  11. cfcollection
  12. cfcomponent
  13. cfcontent
  14. cfcontinue
  15. cfcookie
  16. Tags d-e
5. Tags f
6. Tags g-h
  1. cfgraph
  2. cfgraphdata
  3. cfgrid
  4. cfgridcolumn
  5. cfgridrow
  6. cfgridupdate
  7. cfheader
  8. cfhtmlhead
  9. cfhtmltopdf
  10. cfhtmltopdfitem
  11. cfhttp
  12. cfhttpparam
7. Tags i
  1. cfif
  2. cfimage
  3. cfimap
  4. cfimapfilter
  5. cfimpersonate
  6. cfimport
  7. cfinclude
  8. cfindex
  9. cfinput
  10. cfinsert
  11. cfinterface
  12. cfinvoke
  13. cfinvokeargument
8. Tags j-l
9. Tags m-o
10. Tags p-q
  1. cfparam
  2. cfpdf
  3. cfpdfform
  4. cfpdfformparam
  5. cfpdfparam
  6. cfpdfsubform
  7. cfpod
  8. cfpop
  9. cfpresentation
  10. cfpresentationslide
  11. cfpresenter
  12. cfprint
  13. cfprocessingdirective
  14. cfprocparam
  15. cfprocresult
  16. cfprogressbar
  17. cfproperty
  18. cfquery
  19. cfqueryparam
11. Tags r-s
  1. cfregistry
  2. cfreport
  3. cfreportparam
  4. cfrethrow
  5. cfreturn
  6. cfsavecontent
  7. cfschedule
  8. cfscript
  9. cfsearch
  10. cfselect
  11. cfservlet
  12. cfservletparam
  13. cfset
  14. cfsetting
  15. cfsharepoint
  16. cfsilent
  17. cfslider
  18. cfspreadsheet
  19. cfsprydataset
  20. cfstoredproc
  21. cfswitch
12. Tags t
  1. cftable
  2. cftextarea
  3. cftextinput
  4. cfthread
  5. cfthrow
  6. cftimer
  7. cftooltip
  8. cftrace
  9. cftransaction
  10. cftree
  11. cftreeitem
  12. cftry
13. Tags u-z
  1. cfupdate
  2. cfwddx
  3. cfwebsocket
  4. cfwindow
  5. cfxml
  6. cfzip
  7. cfzipparam
CFML Reference
1. Reserved words and variables
2. Ajax JavaScript functions
3. ColdFusion ActionScript functions
4. ColdFusion mobile functions
5. Application.cfc reference
6. Script functions implemented as CFCs
7. ColdFusion Flash Form style reference
8. ColdFusion event gateway reference
9. ColdFusion C++ CFX Reference
10. ColdFusion Java CFX reference
11. WDDX JavaScript Objects
Cloud services

Description

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

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.

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

Attribute	Req/Opt	Default	Description
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.
delimiter	Optional		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 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.

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 name	getHeaderOnly returns	getAll 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:

Locale	How 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>

Get help faster and easier

New user?