Exporting Messages

The Mail Message control has the ability to export the current message contents as a string or as a text file on the local system. When a message is exported, the complete message including headers, message body and any file attachments are included. The following example uses the CommonDialog control to choose a file name to export the current message to:

Dim nError As Long

On Error GoTo ExportCanceled
CommonDialog1.CancelError = True
CommonDialog1.DefaultExt = ".txt"
CommonDialog1.DialogTitle = "Export Message"
CommonDialog1.FilterIndex = 1
CommonDialog1.Flags = cdlOFNLongNames + cdlOFNOverwritePrompt
CommonDialog1.Filter = "Text Files (*.txt)|*.txt|" & _
                       "email Message Files (*.eml)|*.eml|" & _
                       "All Files (*.*)|*.*"

CommonDialog1.ShowSave
On Error GoTo 0

nError = MailMessage1.ExportMessage(CommonDialog1.FileName)
If nError Then
    MsgBox "Unable to export message to " & _
           CommonDialog1.FileTitle & vbCrLf & _
           MailMessage1.LastErrorString, vbExclamation
    Exit Sub
End If

MsgBox "Exported message to " & CommonDialog1.FileName & vbCrLf & _
       "regarding " & Chr(34) & MailMessage1.Subject & Chr(34), _
       vbInformation

ExportCanceled:
Exit Sub

When a message is exported, headers may be re-ordered and certain headers which contain routing information (such as Received and Return-Path) are omitted by default. These headers are not normally needed when composing or delivering a message, however, there may be situations in which an application needs to preserve these headers or the order in which they were originally received. The ExportMessage method has an optional argument which can be used to specify one or more export options:

Constant Description

mimeOptionDefault The default export options. The headers for the message are written out in a specific consistent order, with custom headers written to the end of the header block regardless of the order in which they were set or imported from another message. If the message contains Bcc, Received, Return-Path, Status or X400-Received header fields, they will not be exported.

mimeOptionAllHeaders All headers, including the Bcc, Received, Return-Path, Status and X400-Received header fields will be exported. Normally these headers are not exported because they are only used by the mail transport system. This option can be useful when exporting a message to be stored on the local system, but should not be used when exporting a message to be delivered to another user.

mimeOptionKeepOrder The original order in which the message header fields were set or imported are preserved when the message is exported.

The mimeOptionAllHeaders and mimeOptionKeepOrder values may be combined if both options are required. For example, the following code would export a message with all of the headers, preserving their original order:

nOptions = mimeOptionAllHeaders Or mimeOptionKeepOrder nError = MailMessage1.ExportMessage(strFileName, nOptions)

Note that the option values are actually bit flags, so a bitwise Or operation is used to combine them. This method is preferred over using simple addition which can produce unexpected results in some cases. Also note that if the ExportMessage method is called without specifying the optional argument, then the value of the Options property is used as a default, such as:

MailMessage1.Options = mimeOptionAllHeaders Or mimeOptionKeepOrder nError = MailMessage1.ExportMessage(strFileName)

This would also cause the message to be exported with all headers and preserve their original order. A general rule of thumb is that if there is an optional argument to a method which corresponds to a property in the control, if that argument is not specified, the property value will be used as a default.

If an application needs to do some processing on the message but doesn't want the overhead of exporting the message to a file, then the message contents can be read using the control's Message property. This property returns a string which contains the complete message, including all headers. The Options property determines whether or not all headers are exported and if the original header order is preserved, just as with the ExportMessage method. It should be noted that this is different than the Text property, which returns only the body of the current message part, not the complete message.