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

Communications tags

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, 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.

See also

cfexchangecalendar,cfexchangeconnection, cfexchangecontact, cfexchangefilter, cfexchangetask, Interacting with Microsoft Exchange Servers in the Developing ColdFusion Applications

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, 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 exceptgetMeetingInfo

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. 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, 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, 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.

The tag places the attachments in the directory specified by the attachmentPath attribute. If you omit the attachmentPath attribute, ColdFusion does not get any attachments; it gets the information about the attachments. This lets you determine the 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.

Use the following syntax to specify an in-memory attachmentPath directory. In-memory files are not written to disk and speed processing of transient data.

attachmentpath = "ram:///path"

The path can include multiple directories, for example ram:///petStore/orders/messageAttachments. Create all directories in the path before you specify the file. For more information on using in-memory files, see Optimizing transient files in the Developing ColdFusion Applications.

The getAttachments action works only if authentication for EWS (Exchange Web Services) is set to basic in the server setup of Exchange. IWA (Integrated Windows Authentication) is not supported.

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 the ColdFusion documentation available online in HTML 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">