ColdFusion 9.0 Resources

cfimap

Description

Queries an IMAP server to retrieve and manage mails within multiple folders.

Syntax

<cfimap 
  action ="DELETE|DELETEFOLDER|CREATEFOLDER|OPEN|CLOSE|RENAMEFOLDER|LISTALLFOLDERS| MARKREAD|MOVEMAIL|GETALL|GETHEADERONLY"     
  attachmentpath = "string"  
  connection = "string" 
  folder = "string" 
  generateuniquefilenames = "yes|no" 
  maxrows = "integer" 
  messagenumber ="integer" 
  name = "string" 
  newfolder = "string" 
  password = "string" 
  port = "integer" 
  recurse = "true|false" 
  secure = "yes|no"  
  server = "IMAP server address" 
  startrow = "integer" 
  secure = "yes|no"  
  stoponerror = "true|false" 
  uid = "integer or comma-delimited list of integers" 
  username = "SMTP user ID">

History

New tag introduced in ColdFusion 9.

Attributes

Attribute	Req/Opt	Default	Description
`action`	Optional	GetHeaderOnly	Returns the message header information for all retrieved mail. Other values for this attribute are: `GetAll`: Returns mail. The information includes the message header information, message text, and any attachments. Set the AttachmentPath attribute to retrieve attachments. `Delete`: Deletes messages from a folder. `Open`: Initiates an open session or connection with the IMAP server. `Close`: Terminates the open session or connection with the IMAP server. `MarkRead`: Marks all messages read from a folder. `CreateFolder`: Creates a folder in the Mailbox. `DeleteFolder`: Deletes a folder in the Mailbox. `RenameFolder`: Renames an existing user-defined folder. `ListAllFolders`: Displays a list of all existing folders in the mailbox or under the folder name defined by the Folder attribute. `MoveMail`: Moves mail from one folder to another.
`attachmentpath`	Optional for GetAll action		Specifies the name of the folder where ColdFusion retrieves attachments. If this folder does not exist, ColdFusion creates. If you do not specify the folder, then the attachment is not saved. Note: If you specify a relative path, then attachments are saved in a temporary folder. This folder is same as one returned by the GetTempDirectory function.
`Connection`	Required for the following actions: Open and Close		Specifies the variable name for the connection/session. If the server attribute has an invalid IP address or invalid domain name, then the connection fails and ColdFusion returns an error message.
`Folder`	Required for the following actions: DeleteFolder, CreateFolder, and RenameFolder Optional for LISTALLFOLDERS, MOVEMAIL, MARKREAD, GETALL, GETHEADERONLY, DELETE.	INBOX (For ListAllFolders action, the default folder is mailbox)	For mail actions: Specifies the folder name where messages are retrieved, moved, or deleted. If folder name is invalid, ColdFusion defaults to INBOX. For folder actions: Specifies the folder name that is deleted (DeleteFolder) or created (CreateFolder) or renamed (RenameFolder). When selecting a subfolder, use the period (.) character as appropriate. For example, when deleting mail in folder ‘Module’ in folder ‘Product.Version.Module’, define the Folder attribute as ‘Product.Version.Module’.
`GenerateUniqueFilenames`	Optional		Ensures that unique file names are generated for each attachment file. The goal is to avoid name conflicts for attachments that have the same filename.
`MaxRows`	Optional		Specifies the number of rows to be marked as read, deleted, or moved across folders. When the value is 1, it signals the row determined by StartRow. Any incremental value marks rows starting from the StartRow.If you have specified the UID or MessageNumber attribute, then MaxRows is ignored.
`MessageNumber`	Optional		Specifies the message number or a comma delimited list of message numbers for retrieval, deletion, marking mail as read, or moving mails. If you set an invalid message number, then the IMAP operation is ignored. For example, if you specify that cfimap deletes a specified message number, and if that message number does not exist, then the operation is ignored. If you have specified the UID attribute, then MessageNumber attribute is ignored.
`Name`	Optional Required for the following actions: GetAll, GetHeaderOnly, and ListAllFolders		Specifies the name for the query object that contains the retrieved message information.
`NewFolder`	Optional Required for the following actions: RenameFolder, MoveMail		Specifies the name of the new folder when you rename a folder or the name of the destination folder where all mails move.
`Password`	Optional Required when action="open" username and password must be specified.		Specifies the password for assessing the users’ e-mail account.
`Port`	Optional	143 or 993	Specifies the IMAP port number. Use 143 for non-secure connections and 993 for secured connections.
`Recurse`	Optional	False	Specifies whether ColdFusion runs the CFIMAP command in subfolders. Recurse works for action=”ListAllFolders”. When recurse is set to ”true”, ColdFusion parses through all folders and subfolders and returns folder/subfolder names and mail information.
`Secure`	Optional	False	Specifies whether the IMAP server uses a Secure Sockets Layer.
`Server`	Optional Required for the Open action		Specifies the IMAP server identifier. You can assign a host name or an IP address as the IMAP server identifier. For example, imap.gmail.com.
`StartRow`	Optional		Defines the first row number for reading or deleting. If you have specified the UID or MessageNumber attribute, then StartRow is ignored. You can also specify StartRow for moving mails.
`StopOnError`	Optional	True	Specifies whether to ignore the exceptions for this operation. When the value is true, it stops processing, displays an appropriate error.
`Timeout`	Optional	60	Specifies the number of seconds to wait before timing out connection to IMAP server. An error message is displayed when timeout occurs.
`Uid`	Optional		Specifies the unique ID or a comma-delimited list of Uids to retrieve, delete, and move mails. If you set invalid Uids, then they are ignored.
`Username`	Optional		Specifies the user name. Typically, the user name is same the e-mail login.

Usage

Open a session or connection with an IMAP server. To open a session, define the server, user name, and password attributes. You can open a connection with an IMAP server by specifying values for the server, user name, password, and connection attributes. For a secure connection, specify secure="true". You can reuse the connection attribute in subsequent CFIMAP tags, without having to specify the server, user name, or password attributes. Once you have established a connection, you can perform the following actions:

Retrieve mail: Retrieve mail using the GetHeaderOnly or GetAll attributes and store the information in a query object. Use the cfdump command to display the content of the query object. You can also download attachments in temporary ColdFusion folder or a new folder as defined by the AttachmentPath attribute.
Delete any unnecessary mail or delete folders. You can delete any user-created folders. Standard folders, such as INBOX, OUTBOX, SEND, cannot be deleted.
Mark multiple mail as read.
Manage mail folders by creating folders, renaming them or moving mail across folders. If you are using sub folders, then use periods (.) to specify the exact path.

Once you have performed all actions, close the session or connection with the IMAP server. For example, mail from your e-mail account in Gmail can be retrieved by setting a connection to the Gmail IMAP server. You can define the login (user name) and set a secure connection. Next, you can quickly retrieve a top-level snapshot of e-mails using the GetHeaderOnly attribute or access full information about e-mails using the GetAll attribute.

Note: Gmail does not support all IMAP features, so some of the attributes such as lines, may not appear when you query gmail. For more information about the IMAP feature limitations in gmail, see the “Does Gmail support all IMAP features?” article.

The following table lists the query information (column names) returned by various cfimap attributes.

Values for “action” attribute

Columns

GetHeaderOnly

ANSWERED, CC, DELETED, DRAFT, FLAGGED, FROM, HEADER, LINES, MESSAGEID, MESSAGENUMBER, RECENT, REPLYTO, RXDDATE, SEEN, SENTDATE, SIZE, SUBJECT, TO, UID

GetAll

ANSWERED, ATTACHMENTFILES, ATTACHMENTS, BODY, CC, CIDS, DELETED, DRAFT, FLAGGED, FROM, HEADER, HTMLBODY, LINES, MESSAGEID, MESSAGENUMBER, RECENT, REPLYTO, RXDDATE, SEEN,SENTDATE, SIZE, SUBJECT, TEXTBODY, TO, UID.

CID is used to find the correct place of an image in an HTML e-mail message that the CFIMAP tag retrieves. If the e-mail message contains more than one embedded image, only the last embedded image is available.

ListAllFolders

FULLNAME (specifies the entire directory structure), NAME, NEW, TOTALMESSAGES, and UNREAD

Note: The cfimap command works best on IMAP4 revision1. IMAP4 revision1 is backwards compatible with IMAP2 and IMAP2bis versions. Any previous versions are no more actively used.

You can get errors in following scenarios:

Accessing an invalid server connection is established. Check the network conditions and whether you are using appropriate server IP address and domain names. Use valid e-mail user names and passwords.
Accessing non-existent folders: Check whether the folder you are accessing exists. Create or rename folders with valid names. You cannot rename core folders. Move mail within existing folders.
Slow network: Verify if the timeout attribute needs a higher value. Actions such as CreateFolder may need longer time to execute. In such cases, adjust the value of the timeout attribute.
Incorrect usage of cfimap attributes: Check if you are using the correct attribute. For example, if you have 15 e-mails in a folder and if the startrow or maxrow attribute has value of 18 then ColdFusion returns an error.
The e-mail client does not recognize IMAP access. Verify whether your e-mail is set up to allow IMAP access. Complete the necessary IMAP access in connection settings section of your e-mail client.
Using incorrect syntax for attributes: Verify that all attributes are defined per syntax.

Example: 1

<!--- Retrieving e-mails from a folder ---> 
<html > 
    <head> 
    <title>IMAP Mail Client</title> 
    </head> 
    <body> 
    <!--- Replace your username and password with valid IMAP email account name and password. ---> 
    <cfimap 
        server = "imap.gmail.com" 
        username = "yourname" 
        action="open" 
        secure="yes" 
        password = "yourpassword" 
        connection = "test.cf.gmail"> 
    <!--- Retrieve header information from the mailbox. ---> 
    <cfimap 
        action="getHeaderOnly" 
        connection="test.cf.gmail" 
        name="queryname"> 
    <cfdump var="#queryname#"> 
    <cfimap 
        action="close" 
        connection = "test.cf.gmail"> 
    </body> 
</html>

Example: 2

<!--- Create a folder; copy mail from Inbox and list all folder info---> 
<html > 
    <head> 
    <title>IMAP Mail Client</title> 
    </head> 
<body> 
    <!--- Replace yourname and yourpassword with valid IMAP email account name and password. ---> 
    <cfimap 
        server = "imap.gmail.com" 
        username = "yourname" 
        action="open" 
        secure="yes" 
        password = "yourpassword" 
        connection = "test.cf.gmail"> 
    <!--- Create a new folder, named Folder1 ---> 
    <cfimap 
        action="CreateFolder" 
        folder="Folder1" 
        connection="test.cf.gmail"> 
    <!--- Move first 2 mails from INBOX to Folder1. ---> 
    <cfimap 
        action="MoveMail" 
        newfolder="Folder1" 
        messagenumber="1,2" 
        stoponerror="true" 
        connection="test.cf.gmail"> 
    <!--- List all folders and get the information in a query. ---> 
    <cfimap action="listallfolders" 
        connection="test.cf.gmail" 
        name="queryname"> 
    <!--- Display query containing all folders information. ---> 
    <cfdump var="#queryname#"> 
    <cfimap 
        action="close" 
        connection = "test.cf.gmail"> 
</body> 
</html>

Example: 3

<!--- Use form-based entry to access cfimap mail account. Save the form with name login.cfm. ---> 
<html> 
<head> 
<title>IMAP Mail Client</title> 
</head> 
<body>     
<cfif IsDefined("form.server")> 
    <!--- Make sure server, username are not empty. ---> 
    <cfif form.server is not "" and form.username is not ""> 
        <cfimap 
           server = "#form.server#" 
           username = "#form.username#" 
           action="open" 
           Secure="yes" 
           password = "#form.pwd#" 
           connection = "#form.server#"> 
        <cfimap 
           action="ListAllFolders" 
           connection="#form.server#" 
           name="queryname"> 
        <h3>Folders in your Inbox <cfoutput>#form.username#</cfoutput></h3> 
        <ol> 
            <cfoutput query = "queryname"> 
                <li>#NAME# - #TOTALMESSAGES# <b>(#UNREAD#)</b></li> 
            </cfoutput> 
        </ol> 
        <!---<cfdump var="#queryname#">---> 
        <cfimap  action="close"           connection = "#form.server#"> 
    </cfif> 
    <cfelse> 
    <form action = "login.cfm " method = "post"> 
        <table> 
            <tr> 
            <td>Enter IMAP mail server</td><td><input type = "Text" name = "server"></td> 
            </tr> 
            <tr> 
            <td>Enter your username</td><td><input type = "Text" name = "username"></td> 
            </tr> 
            <tr> 
            <td>Enter your password</td><td><input type = "password" name = "pwd"></td> 
            </tr> 
            <tr> 
            <td colspan="2"><input type="Submit" value="Get Folder List" name="getFolderList"></td> 
            </tr> 
        </table> 
    </form> 
</cfif> 
</body> 
</html>