cfexchangemail

Description

Gets mail messages and attachments, deletes messages, and sets properties for messages on a Microsoft Exchange server.

History

ColdFusion 8: Added this tag.

Category

Syntax

delete
<cfexchangemail
    required
    action = "delete"
    uid = "message UID,message UID,..."
    optional
    connection = "connection ID"
    folder = "Exchange folder path">

deleteAttachments
<cfexchangemail
    required
    action = "deleteAttachments"
    uid = "message UID"
    optional
    connection = "connection ID">
    folder = "Exchange folder path">

get
<cfexchangemail
    required
    action = "get"
    name = "query identifier"
    optional
    connection = "connection ID"
    folder = "Exchange folder path">

    <cfexchangefilter name = "filter type" value = "filter value">
    <cfexchangefilter name = "filter type" value = "filter value">
    ...
</cfexchangemail>

getAttachments
<cfexchangemail
    required
    action = "getAttachments"
    name = "query identifier"
    uid = "message UID"
    optional
    attachmentPath = "directory path"
    connection = "connection ID"
    folder = "Exchange folder path"
    generateUniqueFilenames = "no|yes">

getMeetingInfo 
<cfexchangemail
    required
    action = "getMeetingInfo"
    meetingUID = "meeting UID"
    name = "query identifier"
    optional
    connection = "connection ID"
    mailUID = "message UID">

move 
<cfexchangemail
    required
    action = "move"
    destinationFolder = "Exchange folder path"
    optional
    connection = "connection ID"
    folder = "Exchange folder path">

    <cfexchangefilter name = "filter type" value = "filter value">
    <cfexchangefilter name = "filter type" value = "filter value">
    ...
</cfexchangemail>

set 
<cfexchangemail
    required
    action = "set"
    message = "#structure with values to set#">
    uid = "message UID">
    optional
    connection = "connection ID"
    folder = "Exchange folder path">

Note: If you omit the connection attribute, you must create a temporary connection by specifying cfexchangeconnection tag attributes in the cfexchangemail tag. In this case, ColdFusion closes the connection when the tag completes. For details, see the cfexchangeconnection tag open action.

Note: You can specify this tag's attributes in an attributeCollection attribute whose value is a structure. Specify the structure name in the attributeCollection attribute and use the tag's attribute names as structure keys.

Attributes

Note: If an attribute, such as folder or destinationFolder takes a folder path, and the folder name contains forward slashes (/), specify the folder name by using the _xF8FF_ escape character to prevent exchange from interpreting the character as a path delimiter.

Attribute	Action	Req/Opt	Default	Description
action	all	Required		The action to take. Must be one of the following values: `delete` `deleteAttachments` `get` `getAttachments` `getMeetingInfo` `move` `set`
attachmentPath	getAttachments	Optional		The filepath of the directory in which to put the attachments. If the directory does not exist, ColdFusion creates it. Note: If you omit this attribute, ColdFusion does not save any attachments. If you specify a relative path, the path root is the ColdFusion temporary directory, which is returned by the `GetTempDirectory` function.
connection	all	Optional		The name of the connection to the Exchange server, as specified in the `cfexchangeconnection` tag. If you omit this attribute, you must create a temporary connection by specifying `cfexchangeconnection` tag `open` action attributes in the `cfexchangecalendar` tag.
destinationFolder	move	Required		The forward slash (/) delimited path, relative to the root of the mailbox, of the folder to which to move the message or messages.
folder	all except getMeetingInfo	Optional		The forward slash (/) delimited path, relative to the root of the mailbox, of the folder that contains the message or messages. The `cfexchangemail` tag looks in the specified folder only, and does not search subfolders. For the `get` and `move` actions specifying a `cffexchangefilter` child tag with a `name="folder"` attribute is equivalent to setting this attribute, and takes precedence over this attribute's value. If you omit this attribute, or for `get` and `move` actions, if you do not use the corresponding `cfexchangefilter` setting, Exchange looks in the top level of the Inbox.
generateUniqueFilenames	getAttachments	Optional	no	A Boolean value that specifies whether to generate unique filenames if multiple attachments have the same filenames. If two or more attachments have the same filename and this option is `yes,` ColdFusion appends a number to the filename body (before the extension) of any conflicting filenames. Thus, if three attachments have the name myfile.txt, ColdFusion saves the attachments as myfile.txt, myfile1.txt, and myfile2.txt.
mailUID	getMeetingInfo	Optional		The case-sensitive UID of the mail message that contains the meeting request, response, or cancellation notification. Use this attribute if there are multiple messages about a single meeting.
meetingUID	getMeetingInfo	Required		The case-sensitive UID of the meeting for which you received the notification.
message	set	Required		A reference to a structure that contains the properties to be set and their values. You must specify this attribute in number signs (#). For more information on the message structure, see Usage.
name	get getAttachments getMeetingInfo	Required		The name of the ColdFusion query variable that contains the returned mail messages or the retrieved information about the attachments or meeting. For more information on the returned data, see Usage.
uid	delete getAttachments set	Required		The case-sensitive UIDs of the messages on which to perform the action. For the `delete` action, this attribute can be a comma-delimited list of UID values. The `deleteAttachments, getAttachments`, and `set` actions allow only a single UID value.

Usage

The cfexchangemail tag performs mail actions on an Exchange server that you cannot do by using the cfmail tag. (You must use the cfmail tag to send, forward, and reply to mail messages.) Use the cfexchangemail tag to perform the following actions:

Permanently delete one or more mail messages from the server.
Get the attachments for a specific message.
Get one or more messages that conform to an optional set of filter specifications, such as the subject, sender or recipient ID, time received, and so on.
Get the attachments for a specific message.
Get detailed information about a meeting for which you have a notification, such as a meeting request or cancellation notice.
Move one or more messages from one folder to another, including to the Deleted Items folder.
Set the properties of a specific mail message.

To use this tag, you must have a connection to an Exchange server. If you are using multiple tags that interact with the exchange server, such as if you are creating several contact records, you should use the cfexchangeconnection tag to create a persistent connection. You then specify the connection identifier in each cfexchangemail tag, or any other ColdFusion Exchange tag, if you are also accessing tasks, contacts, or connections. Doing this saves the overhead of creating and closing the connection for each tag.

Alternatively, you can create a temporary connection that lasts only for the time that ColdFusion processes the single cfexchangemail tag. To do this, you specify the connection attributes directly in the cfexchangemail tag. For details on the connection attributes, see the cfexchangeconnection tag.

The delete action

The delete action permanently deletes a message from the server, and is equivalent to the Outlook Shift-Delete keystroke action. Use the move action to move a message to the Deleted Items folder, which is equivalent to the Outlook Delete keystroke action.

When you specify the delete action you must specify a uid attribute with a comma-delimited list of one or more Exchange UIDs that identify the tasks that you want to delete. You can use the get action, with an appropriate filter expression, to determine the UID values to specify.

If all UIDs that you specify are invalid, the cfexchangemail tag generates an error. If at least one UID is valid, the tag ignores any invalid UIDs and deletes the items specified by the valid UID.

The get action

When you specify the get action, you use child cfexchangefilter tags to specify the messages to get. For detailed information, see cfexchangefilter. When the tag completes processing, the query object specified by the name attribute contains one record for each matching message that was found. Each record has the following columns:

Column	Description
BCC	A comma-delimited list of Exchange user IDs or web e-mail .
CC	A comma-delimited list of Exchange user IDs or web e-mail addresses.
Folder	The forward slash (/) delimited path from the root of the Exchange mailbox to the mail folder containing the message.
FromID	An Exchange user IDs or web e-mail addresses.
HasAttachment	A Boolean value that indicates whether the message has at least one attachment.
HTMLMessage	A string containing a HTML-formatted version of the message.
IsRead	A Boolean value.
Message	A string with a plain-text version of the message contents.
MessageType	One of the following strings: `Mail` `Meeting_Cancel` `Meeting_Request` `Meeting_Response`
MeetingResponse	If the message type is `Meeting_response,` this column contains the response code as one of the following strings: `Accept`, `Decline`, or `Tentative`. This field is not used for other message types.
MeetingUID	If the message type is `Meeting_Cancel`, `Meeting_request`, or `Meeting_response` this column contains the UID of the calendar event for which this message was sent. Use this value in the `cfexchangecalendar` tag to respond to a request. This field is not used for the `Mail` message type.
Sensitivity	One of the following strings: `public` `private` `normal` `company-confidential`
Subject	A string.
TimeReceived	A Coldfusion date-time object.
TimeSent	A Coldfusion date-time object.
ToId	A comma-delimited list of Exchange user IDs or web mail IDs.
UID	The Exchange UID of the message.

Note: An invitation sender can get a meeting request message only if the sender is on the attendee list.

The getAttachments action

When you use the getAttachments action, you must specify a single UID and a name attribute. The cfexchangecontact tag populates a query object specified by the name attribute with one record for each attachment. Each record has the following information about the mail attachment specified by the UID:

Column name	Description
attachmentFileName	The filename of the attachment.
attachmentFilePath	The absolute path of the attachment file on the server. If you omit the `attachmentPath` attribute, this column contains the empty string.
CID	The content-ID of the attachment. Used in HTML img tags to embed images in a message.
mimeType	The MIME type of the attachment, such as text/html.
isMessage	A Boolean value that specifies whether the attachment is a message.
size	The attachment size in bytes.

If you omit the attachmentPath attribute, ColdFusion does not get any attachments; it gets the information about the attachments. This lets you determine the event's attachments without incurring the overhead of getting the attachment files.

If a message has multiple attachments with the same name, the attachment information structure always lists the attachments with their original, duplicate, names, even if you specify generateUniqueFilenames="yes". The generateUniqueFilenames attribute only affects the names of the files on disk.

The getMeetingInfo action

You use the getMeetingInfo action to get meeting-specific information, such as the meeting start and end times, location, and so on, about a meeting for which you have received a notification message, such as an invitation request or cancellation notice. This information is not available directly in the notification message query object that is returned by the get action.

Note: At the time of publication, the following information does not completely reflect the behavior of the getMeetingInfo action. For updated information, see cfexchangemail in ColdFusion 8 LiveDocs on the Adobe website.

When you specify the getMeetingInfo action, you specify a meetingUID attribute with the UID of the meeting. You get this UID value from the query record that is returned by the get action. You can optionally specify a messageUID attribute with the UID of the specific message that contains the notification; if you receive multiple messages about a single meeting, you can use this attribute to select a single notification message.

When the tag completes processing, the query object specified by the name attribute contains one record for each matching message that was found. Each record has the following columns:

Field	Description
AllDayEvent	A Boolean value that indicates whether this is an all day event.
Duration	The duration of the event in minutes.
EndTime	The end time of the event, in ColdFusion ODBC date-time format.
From	The mail ID of the person who sent the meeting notification.
HasAttachment	A Boolean value that indicates whether this event has attachments.
Importance	One of the following values: `high` `normal` `low`
IsRecurring	A Boolean value that indicates whether this event repeats.
Location	A string that specifies the location of the event.
MeetingUID	The UID of the event in the calendar.
Message	A string that contains a message about the event.
OptionalAttendees	A comma-delimited list of mail IDs.
Organizer	A string. This value is not necessarily an Exchange ID or e-mail address.
Reminder	The time, in minutes before the event, at which to display a reminder message.
RequiredAttendees	A comma-delimited list of mail IDs.
Resources	A comma-delimited list of mail IDs for Exchange scheduling resources, such as conference rooms and display equipment.
Sensitivity	One of the following values: `normal` `company-confidential` `personal` `private`
StartTime	The start time of the event, in ODBC date-time format.
Subject	A string describing the event subject.
TimeReceived	The time the message was received, in ODBC date-time format.
UID	The UID of the message that contains the event notification.

The move action

Use the move action to move one or more messages from one folder to another folder. You can use this action to move messages to the Deleted Items folder, which is equivalent to the Outlook Delete keystroke action.

When you specify the move action you specify the destination folder, and optionally the folder containing the messages to move. (The default source folder is the Inbox). You use child cfexchangefilter tags to specify the messages to get. For detailed information, see cfexchangefilter.

The set action

When you specify the set action, the structure specified by the message attribute contains key-value pairs that specify the message properties to set. The following table lists the key names and their valid values:

Key name	Valid values
IsRead	`yes`, `no`
Importance	`high`, `normal`, `low`
Sensitivity	`normal`, `company-confidential`, `personal`, `private`

Example

The following example gets the attachments to all mail messages in the Inbox from docuser2 in the last week. It puts each message's attachments in a directory with a unique name. It cannot use the UID as a filename because, for each message with attachments, the UID can contain the application reports of the UID, directory path, subject, date, and sender of the message, followed by a table that lists the message's attachments. The table includes the attachment name, size, and MIME type.

<!--- Index for message attachement directory --->
<cfset i=1>
<!--- Dates for date range --->
<cfset rightNow = Now()>
<cfset lastWeek = DateAdd("d","-7", rightNow)>

<cfexchangeconnection
    action="open"
    username ="#user1#"
    password="#password1#"
    server="#exchangeServerIP#"
    connection="testconn1">

<cfexchangemail action="get" folder="Inbox " name="weeksMail" connection="testconn1">
    <cfexchangefilter name="FromID" value="docuser2">
    <cfexchangefilter name="TimeSent" from="#lastWeek#" to="#rightNow#">
</cfexchangemail>

<cfloop query="weeksMail">
    <cfif weeksmail.HasAttachment>
        <cfexchangemail action="getAttachments" 
            connection="testconn1"
            folder="Inbox/MailTest"
            uid="#weeksmail.uid#" 
            name="attachData" 
            attachmentPath="C:\temp\cf_files\attachments\msg_#i#"
            generateUniqueFilenames="yes">
        <cfoutput>
            Message ID #weeksmail.uid# attachments are in the directory
                C:\temp\cf_files\attachments\Msg_#i#<br />
            <br />
                Message information:<br />
                Subject: #weeksmail.Subject#<br />
                Sent: #dateFormat(weeksmail.TimeSent)#<br />
                From:  #weeksmail.FromID#<br />
            <br />
            Attachments<br />
            <cftable query="attachData" colheaders="yes">
                <cfcol header="File Name" text="#attachmentFilename#">
                <cfcol header="Size" text="#size#">
                <cfcol header="MIME type" text="#mimeType#">
            </cftable>
        </cfoutput>
        <cfset i++>
    </cfif>
</cfloop>
<cfexchangeconnection action="close" connection="testconn1">

Adobe ColdFusion 8

cfexchangemail

Related Information

Help Resource Center