# CFPOP

CFPOP retrieves and deletes email messages from a POP mail server. See also CFMAIL.

### Syntax

    <CFPOP SERVER="servername"
        PORT="port_number"
        USERNAME="username"
        PASSWORD="password"
        ACTION="action"
        NAME="queryname"
        MESSAGENUMBER="number"
        ATTACHMENTPATH="path"
        TIMEOUT="seconds"
        MAXROWS="number"
        STARTROW="number"
        GENERATEUNIQUEFILENAMES="boolean">

#### SERVER

Required. Host name (biff.upperlip.com) or IP address (192.1.2.225) of the POP server.

#### PORT

Optional. Defaults to the standard POP port, 110.

#### USERNAME

Optional. If no user name is specified, the POP connection is anonymous.

#### PASSWORD

Optional. Password corresponds to user name.

#### ACTION

Optional. Specifies the mail action. There are three possible values:

- GetHeaderOnly -- (Default) Returns message header information only.
- GetAll -- Returns message header information, message text, and attachments if ATTACHMENTPATH is specified.
- Delete -- Deletes messages on the POP server.

  Note | Two retrieve options are offered to maximize performance. 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. See the Message Header and Body Columns table, which follows the CFPOP attribute descriptions, for information on retrieving header and body information form the query when you specify GetHeaderOnly or GetAll.

#### NAME

Optional. The name you assign to the index query. Required for ACTION="GetHeaderOnly" and ACTION="GetAll".

#### MESSAGENUMBER

Optional. Specifies the message number(s) for the given action. MESSAGENUMBER is required for ACTION="Delete". If it is provided for ACTION="GetHeaderOnly" or ACTION="GetAll", only referenced messages will be retrieved. If it is omitted for ACTION="GetHeaderOnly"or ACTION="GetAll", all messages available on the server are returned.

MESSAGENUMBER can contain individual message numbers or a comma-separated list of message numbers. Invalid message numbers will be ignored.

#### ATTACHMENTPATH

Optional. Allows attachments to be written to the specified directory when ACTION="GetAll". If an invalid ATTACHMENTPATH is specified, no attachment files are written to the server.

#### TIMEOUT

Optional. Specifies the maximum amount of time in seconds to wait for mail processing. Defaults to 60 seconds.

#### MAXROWS

Optional. Specifies the maximum number of entries for mail queries. This attribute is ignored if MESSAGENUMBER is specified.

#### STARTROW

Optional. Specifies the first row number to be retrieved. Default is 1. This attribute is ignored if MESSAGENUMBER is specified.

#### GENERATEUNIQUFILENAMES

Optional. Boolean indicating whether to generate unique file names for the files attached to an email message in order to avoid naming conflicts when the files are saved. The default is NO.

#### CFPOP Query Variables

The following table describes the query variables that are returned by CFPOP. The example illustrates their use.

CFPOP Query Variables
Variable Names | Description
--- | ---
    queryname.RecordCount
| The total number of records returned by the query.
    queryname.CurrentRow
| The current row of the query being processed by CFOUTPUT.
    queryname.ColumnList
| The list of the column names in the query.

###

### Message Header and Body Columns

The following table lists the message header and body columns that are returned by CFPOP when you specify the ACTION attribute to be either GetHeaderOnly or GetAll. All of the columns are returned if you specify GetAll, but only header information is returned when you specify GetHeaderOnly.

Message Header and Body Columns
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

### Usage

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 to determine what to do.

Date-Time Parsing According to Locale
Locale | What to do?
--- | ---
    English (US) locale
| Use the ParseDateTime function and specify the POP attribute, which converts the date-time value to Greenwich Meantime.
    Other locales
| Extract the date portion of the string and pass it to the LSParseDateTime function, then add or subtract the conversion time, depending on the locale.

See also the description of the SetLocale function.

For complete usage information on CFPOP, see Developing Web Applications with ColdFusion.

### Example

    <!--- This view-only example shows the use of CFPOP --->
    <HTML>
    <HEAD>
    <TITLE>CFPOP Example</TITLE>
    </HEAD>

    <BODY>
    <H3>CFPOP Example</H3>
    <P>CFPOP allows you to retrieve and manipulate mail
    in a POP3 mailbox.  This view-only example shows how to
    create one feature of a mail client, allowing you to display
    the mail headers in a POP3 mailbox.

    <P>Simply uncomment this code and run with a mail-enabled CF Server to
    see this feature in action.
    <!---
    <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>
    --->

    </BODY>
    </HTML>