User Guide Cancel

cfimap

Last updated on May 30, 2024 | Also applies to ColdFusion

ColdFusion

Open app

CFML Reference User Guide
ColdFusion functions
ColdFusion Tags
1. ColdFusion tag summary
2. ColdFusion tags by category
  1. Application framework tags
    1. cfapplication
    2. cfassociate
    3. cferror
    4. cfimport
    5. cfinterface
    6. cflock
    7. cfscript
    8. cfthread
  2. Communications tags
  3. Database manipulation tags
  4. Data output tags
    1. cfchart
    2. cfchartdata
    3. cfchartseries
    4. cfcol
    5. cfcontent
    6. cfdocument
    7. cfdocumentitem
    8. cfdocumentsection
    9. cfflush
    10. cfheader
    11. cflog
    12. cfoutput
    13. cfpresentation
    14. cfpresentationslide
    15. cfpresenter
    16. cfprocessingdirective
    17. cfprint
    18. cfreport
    19. cfreportparam
    20. cfsilent
    21. cftable
  5. Debugging tags
    1. cfdump
    2. cftimer
    3. cftrace
  6. Exception handling tags
    1. cfcatch
    2. cferror
    3. cffinally
    4. cfrethrow
    5. cfthrow
    6. cftry
  7. Extensibility tags
    1. cfchart
    2. cfchartdata
    3. cfchartseries
    4. cfcollection
    5. cfcomponent
    6. cfexecute
    7. cfftp
    8. function
    9. cfindex
    10. cfinterface
    11. cfinvoke
    12. cfinvokeargument
    13. cfobject
    14. cfproperty
    15. cfreport
    16. cfreportparam
    17. cfreturn
    18. cfsearch
    19. cfsharepoint
    20. cfspreadsheet
    21. cfwddx
    22. cfxml
  8. File management tags
    1. cfdirectory
    2. cffile
    3. cffileupload
    4. cfftp
    5. cfzip
    6. cfzipparam
  9. Flow-control tags
    1. cfabort
    2. cfbreak
    3. cfcase
    4. cfcontinue
    5. cfdefaultcase
    6. cfelse
    7. cfelseif
    8. cfexecute
    9. cfexit
    10. cfif
    11. cfinclude
    12. cflocation
    13. cfloop
    14. cfrethrow
    15. cfswitch
    16. cfthrow
    17. cftry
  10. Forms tags
    1. cfapplet
    2. cfcalendar
    3. cffileupload
    4. cfform
    5. cfformgroup
    6. cfformitem
    7. cfgrid
    8. cfgridcolumn
    9. cfgridrow
    10. cfgridupdate
    11. cfinput
    12. cfpdf
    13. cfpdfform
    14. cfpdfformparam
    15. cfpdfparam
    16. cfpdfsubform
    17. cfselect
    18. cfslider
    19. cftextarea
    20. cftree
    21. cftreeitem
  11. Internet Protocol tags
    1. cfajaximport
    2. cfajaxproxy
    3. cfftp
    4. cffeed
    5. cfimap
    6. cfhttp
    7. cfhttpparam
    8. cfldap
    9. cfmail
    10. cfmailparam
    11. cfmailpart
    12. cfpop
    13. cfsprydataset
  12. Page processing tags
    1. cfcache
    2. cfcontent
    3. cfflush
    4. cfheader
    5. cfhtmlhead
    6. cfinclude
    7. cfprocessingdirective
    8. cfsetting
    9. cfsilent
  13. Security tags
  14. Variable manipulation tags
    1. cfcookie
    2. cfdump
    3. cfparam
    4. cfregistry
    5. cfsavecontent
    6. cfschedule
    7. cfset
    8. cfsetting
  15. Other tags
    1. cfimage
    2. cflog
    3. cfregistry
3. Tags a-b
4. Tags c
  1. cfcache
  2. cfcalendar
  3. cfcase
  4. cfcatch
  5. cfchart
  6. cfchartdata
  7. cfchartseries
  8. cfclient
  9. cfclientsettings
  10. cfcol
  11. cfcollection
  12. cfcomponent
  13. cfcontent
  14. cfcontinue
  15. cfcookie
  16. Tags d-e
5. Tags f
6. Tags g-h
  1. cfgraph
  2. cfgraphdata
  3. cfgrid
  4. cfgridcolumn
  5. cfgridrow
  6. cfgridupdate
  7. cfheader
  8. cfhtmlhead
  9. cfhtmltopdf
  10. cfhtmltopdfitem
  11. cfhttp
  12. cfhttpparam
7. Tags i
  1. cfif
  2. cfimage
  3. cfimap
  4. cfimapfilter
  5. cfimpersonate
  6. cfimport
  7. cfinclude
  8. cfindex
  9. cfinput
  10. cfinsert
  11. cfinterface
  12. cfinvoke
  13. cfinvokeargument
8. Tags j-l
9. Tags m-o
10. Tags p-q
  1. cfparam
  2. cfpdf
  3. cfpdfform
  4. cfpdfformparam
  5. cfpdfparam
  6. cfpdfsubform
  7. cfpod
  8. cfpop
  9. cfpresentation
  10. cfpresentationslide
  11. cfpresenter
  12. cfprint
  13. cfprocessingdirective
  14. cfprocparam
  15. cfprocresult
  16. cfprogressbar
  17. cfproperty
  18. cfquery
  19. cfqueryparam
11. Tags r-s
  1. cfregistry
  2. cfreport
  3. cfreportparam
  4. cfrethrow
  5. cfreturn
  6. cfsavecontent
  7. cfschedule
  8. cfscript
  9. cfsearch
  10. cfselect
  11. cfservlet
  12. cfservletparam
  13. cfset
  14. cfsetting
  15. cfsharepoint
  16. cfsilent
  17. cfslider
  18. cfspreadsheet
  19. cfsprydataset
  20. cfstoredproc
  21. cfswitch
12. Tags t
  1. cftable
  2. cftextarea
  3. cftextinput
  4. cfthread
  5. cfthrow
  6. cftimer
  7. cftooltip
  8. cftrace
  9. cftransaction
  10. cftree
  11. cftreeitem
  12. cftry
13. Tags u-z
  1. cfupdate
  2. cfwddx
  3. cfwebsocket
  4. cfwindow
  5. cfxml
  6. cfzip
  7. cfzipparam
CFML Reference
1. Reserved words and variables
2. Ajax JavaScript functions
3. ColdFusion ActionScript functions
4. ColdFusion mobile functions
5. Application.cfc reference
6. Script functions implemented as CFCs
7. ColdFusion Flash Form style reference
8. ColdFusion event gateway reference
9. ColdFusion C++ CFX Reference
10. ColdFusion Java CFX reference
11. WDDX JavaScript Objects
Cloud services

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"
delimeter = "delimeter char"
username = "SMTP user ID">

History

New tag introduced in ColdFusion 9.
New attribute named delimeter is introduced in ColdFusion 11.

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 RenameFolderOptional 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	OptionalRequired for the following actions: GetAll, GetHeaderOnly, and ListAllFolders		Specifies the name for the query object that contains the retrieved message information.
NewFolder	OptionalRequired 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	OptionalRequired 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	OptionalRequired for the Open action		Specifies the IMAP server identifier. You can assign a host name or an IP address as the IMAP server identifier.
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.
delimiter	Optional		The value of the uid attribute can be a comma-separated list of UIDs. If the delimiter attribute is specified, the value of delimiter will be used as a delimiter instead of comma.

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.

Gmail is not a complete IMAP implementation so some of the features of a regular IMAP server may not work with Gmail.

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. Replace "server address" with your IMAP server address---> 
<cfimap 
server = "server address" 
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. Replace "server address" with your IMAP server address---> 
<cfimap 
server = "server address" 
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>

Get help faster and easier

New user?