CFML Reference

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

Copyright © 2002, Macromedia Inc. All rights reserved.

Comments