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

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"
port
Optional
110
POP port
username
Optional
Anonymous
  • A user name
  • "Anonymous"
password
Optional
 
Password that corresponds to username.
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
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
60
Maximum time, in seconds, to wait for mail processing.
maxRows
Optional
999999
Number of messages to return, starting with the number in startRow. If messageNumber is specified, this attribute is ignored.
startRow
Optional
1
First row number to get. If messageNumber is specified, this attribute is ignored.
generateUniqueFilenames
Optional
No
  • Yes: Generate unique filenames for files attached to an e-mail message, to avoid naming conflicts when files are saved
  • No

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

Comments