# Handling POP Mail

This section gives an example of each of the following usages:

- Retrieving only message headers
- Retrieving a message body
- Retrieving attachments
- Deleting messages

## Returning only message headers

The header includes:

- DATE
- FROM
- MESSAGENUMBER
- REPLYTO
- SUBJECT
- CC
- TO

| To retrieve only the message header:

1. Create a new file in Studio.
2. Modify the file so that it appears as follows:

       <HTML>
       <HEAD>
       <TITLE>POP Mail Message Header Example</TITLE>
       </HEAD>

       <BODY>
       <H2>This example retrieves message
       header information:</H2>

       <CFPOP SERVER="mail.company.com"
           USERNAME=#username#
           PASSWORD=#password#
           ACTION="GetHeaderOnly"
           NAME="Sample">

       <CFOUTPUT QUERY="Sample">
           MessageNumber: #HTMLEditFormat(Sample.MESSAGENUMBER)# <BR>
           To: #HTMLEditFormat(Sample.TO)# <BR>
           From: #HTMLEditFormat(Sample.FROM)# <BR>
           Subject: #HTMLEditFormat(Sample.SUBJECT)# <BR>
           Date: #HTMLEditFormat(Sample.DATE)# <BR>
           Cc: #HTMLEditFormat(Sample.CC)# <BR>
           ReplyTo: #HTMLEditFormat(Sample.REPLYTO)# <BR>
       </CFOUTPUT>

       </BODY>
       </HTML>

3. Change the following line so that it refers to a valid POP mail server, as well as a valid user name and password:

       <CFPOP SERVER="mail.company.com"
           USERNAME=#username#
           PASSWORD=#password#

4. Save the file as `hdronly.cfm` in `myapps` under the Web root directory.

This code retrieves the message headers and stores them in a CFPOP result set called Sample.

You can enclose header information in HTML coding and use the ColdFusion function HTMLCodeFormat to replace HTML tags with escaped characters, such as `&gt;` for `>` and `&lt;` for `<`.

In addition, you can process the date returned by CFPOP with ParseDateTime, which accepts an argument for converting POP date/time objects into GMT (Greenwich Mean Time).

See the CFML Language Reference for information on these ColdFusion functions.

You can reference any of these columns in a CFOUTPUT tag, as the following example shows.

    <CFOUTPUT>
        #ParseDateTime(queryname.date, "POP")#
        #HTMLCodeFormat(queryname.from)#
        #HTMLCodeFormat(queryname.messagenumber)#
    </CFOUTPUT>

## Returning an entire message

When you use the CFPOP tag with ACTION="GetAll", ColdFusion returns the same columns returned with GETHEADERONLY, as well as two additional columns, BODY and HEADER.

| To retrieve an entire message:

1. Create a new file in Studio.
2. Modify the file so that it appears as follows:

       <HTML>
       <HEAD>
       <TITLE>POP Mail Message Body Example</TITLE>
       </HEAD>

       <BODY>
       <H2>This example adds retrieval of
       the message body:</H2>

       <CFPOP SERVER="mail.company.com"
           USERNAME=#username#
           PASSWORD=#password#
           ACTION="GetAll"
           NAME="Sample">

       <CFOUTPUT QUERY="Sample">
           MessageNumber: #HTMLEditFormat(Sample.MESSAGENUMBER)# <BR>
           To: #HTMLEditFormat(Sample.TO)# <BR>
           From: #HTMLEditFormat(Sample.FROM)# <BR>
           Subject: #HTMLEditFormat(Sample.SUBJECT)# <BR>
           Date: #HTMLEditFormat(Sample.DATE)# <BR>
           Cc: #HTMLEditFormat(Sample.CC)# <BR>
           ReplyTo: #HTMLEditFormat(Sample.REPLYTO)# <BR>
           Body: #HTMLCodeFormat(Sample.BODY)# <BR>
           Header: #HTMLCodeFormat(Sample.HEADER)# <BR>
       </CFOUTPUT>

       </BODY>
       </HTML>

3. Change the following line so that it refers to a valid POP mail server, as well as a valid user name and password:

       <CFPOP SERVER="mail.company.com"
           USERNAME=#username#
           PASSWORD=#password#

4. Save the file as `hdrbody.cfm` in `myapps` under the Web root directory.

## Returning attachments with messages

When you use the CFPOP tag with ACTION="GetAll", and add the ATTACHMENTPATH attribute, ColdFusion returns two additional columns:

- ATTACHMENTS contains a a tab-separated list of all source attachment names.
- ATTACHMENTFILES contains a tab-separated list of the actual temporary filenames written to the server. Use the CFFILE tag to delete the temporary files.

Not all messages have attachments. If a message has no attachments, both ATTACHMENTS and ATTACHMENTFILES will be equal to an empty string.

| To retrieve all parts of a message including attachments:

1. Create a new file in Studio.
2. Modify the file so that it appears as follows:

       <HTML>
       <HEAD>
       <TITLE>POP Mail Message Attachment Example</TITLE>
       </HEAD>

       <BODY>
       <H2>This example retrieves message header,
       body, and all attachments:</H2>

       <CFPOP SERVER="mail.company.com"
           USERNAME=#username#
           PASSWORD=#password#
           ACTION="GetAll"
           ATTACHMENTPATH="c:\attachdir"
           NAME="Sample">

       <CFOUTPUT QUERY="Sample">
           MessageNumber: #HTMLEditFormat(Sample.MESSAGENUMBER)# <BR>
           To: #HTMLEditFormat(Sample.TO)# <BR>
           From: #HTMLEditFormat(Sample.FROM)# <BR>
           Subject: #HTMLEditFormat(Sample.SUBJECT)# <BR>
           Date: #HTMLEditFormat(Sample.DATE)# <BR>
           Cc: #HTMLEditFormat(Sample.CC)# <BR>
           ReplyTo: #HTMLEditFormat(Sample.REPLYTO)# <BR>
           Attachments: #HTMLEditFormat(Sample.ATTACHMENTS)# <BR>
           Attachment Files: #HTMLEditFormat(Sample.ATTACHMENTFILES)# <BR>
           Body: #HTMLCodeFormat(Sample.BODY)# <BR>
           Header: #HTMLCodeFormat(Sample.HEADER)# <BR>
       </CFOUTPUT>

       </BODY>
       </HTML>

3. Change the following line so that it refers to a valid POP mail server, as well as a valid user name and password:

       <CFPOP SERVER="mail.company.com"
           USERNAME=#username#
           PASSWORD=#password#

4. Save the file as `attach.cfm` in `myapps` under the Web root directory.

Note | To avoid duplicate file names when saving attachments, use the GENERATEDUNIQUEFILENAMES attribute of CFPOP and set it to Yes.

## Deleting messages

By default, retrieved messages are not deleted from the POP mail server. If you want to delete retrieved messages, you must set the ACTION attribute to Delete.

Note | Once a message is deleted, it's gone for good.

The MESSAGENUMBER attribute returned by all CFPOP retrievals contains the message number you need to pass back to the POP mail server to have the corresponding message deleted. A few notes:

Note | Message numbers are reassigned at the end of every POP mail server communication that contains a delete action. For example, if four messages are retrieved from a POP mail server, the message numbers returned will be 1,2,3,4. If messages 1 and 2 are then deleted within a single CFPOP tag, messages 3 and 4 will be assigned message numbers 1 and 2, respectively.

| To delete messages:

1. Create a new file in Studio.
2. Modify the file so that it appears as follows:

       <HTML>
       <HEAD>
       <TITLE>POP Mail Message Delete Example</TITLE>
       </HEAD>

       <BODY>
       <H2>This example deletes messages:</H2>

       <CFPOP SERVER="mail.company.com"
           USERNAME=#username#
           PASSWORD=#password#
           ACTION="Delete"
           MESSAGENUMBER="1,2,3">

       </BODY>
       </HTML>

3. Change the following line so that it refers to a valid POP mail server, as well as a valid user name and password:

       <CFPOP SERVER="mail.company.com"
           USERNAME=#username#
           PASSWORD=#password#

4. Save the file as `msgdel.cfm` in `myapps` under the Web root directory.