Uploads a mail message to the specified folder, assigns the specified date and flags to this message, and retrieves UID assigned to the uploaded message by the server.

Parameters

msg

A reference to the MailMessage object representing the message to be uploaded.

folderName

The full name of the folder to upload the message to.

flags

The string containing the message flags (in IMAP4 format) to be assigned to the message, or a null reference (Nothing in Visual Basic) to set default flags at the discretion of the server.

dateTimeString

The string containing datetime (in IMAP4 format) to be assigned to the INTERNALDATE attribute of the message (the date of receiving the message by the server), or a null reference to let the server assign its current datetime value.

batchMode

If true and LITERAL+ extension is supported by the server, the message will be uploaded in a single network operation; otherwise, in two operations.

result

A reference to the UidPlusResult object to be filled with the outcome of the upload operation reported by UIDPLUS enabled server (the outcome includes the UID assigned to the uploaded message and the UIDVALIDITY of the folder the message was uploaded to), or a null reference if the application does not need this information.

Return Value

true if the message was uploaded successfully; otherwise, false.

Remarks

This method implements APPEND command of the IMAP4 protocol.

To upload a file, the developer can first load it into MailMessage object using LoadMessage method, and then call UploadMessage passing a reference to this MailMessage object. There is no extra overhead on parsing the message since LoadMessage just reads a file into memory. The MailMessage won't parse the contained message unless the application starts accessing its properties or methods (so-called "lazy" model).

To upload a mail message just sent using Smtp component, the developer call UploadMessage method passing a reference to the Message property.

To get standard message flags as string in IMAP4 format (e.g. "\Seen \Flagged"), the developer can use SystemFlagsToString method.

In addition to the flags specified by the application, the server also sets "\Recent" flag. Thus, the uploaded message will always have at least "\Recent" flag set.

To get datetime string in IMAP4 format (e.g. "01-May-2004 05:26:59 -0600"), the developer can use GetImapDateTimeString method.

batchMode value is ignored if the server does not support LITERAL+ extension. However, even if LITERAL+ is supported, the developer may still decide not to use batch mode if there is a risk that the server will reject the message due to its size. If this happens, the client will waste bandwidth transferring the entire message. If the client wouldn't have used the LITERAL+, this could have been avoided, because the server would have rejected the initial small request containing the length of the data to be uploaded, and thus second large request containing the actual message data would have never been sent. In general, however, if the application is not going to upload very large messages frequently, it's more effective to keep batch mode on. Other overloads of UploadMessage method always upload messages in batch mode if LITERAL+ is supported.

When result is specified and the server supports UIDPLUS extension, UploadMessage method will set the supplied UidPlusResult object properties as below:

If UIDPLUS capability is not supported by the server, IsSupported will be set to false. When working with the server which lacks UIDPLUS support, the application can obtain UID of the uploaded message from UidNext value of FolderStatus object returned by GetFolderStatus method. However, the application must call GetFolderStatus method BEFORE making upload (see the sample).

The developer can also try to avoid calling GetFolderStatus method if the UIDNEXT value is already available in UidNext property (the destination folder must be selected in this case, and some other restrictions apply, see remarks in UidNext topic for more information).

Exceptions

Example

This sample loads the mail message from a file, and then uploads it to the Inbox folder on the server specifying "12-Apr-2006 19:30:00 +0100" as date of receiving the message by the server (INTERNALDATE), and setting "\Seen" and "\Flagged" flags (the server will also set "\Recent" flag). Finally, the UID value assigned to the message is displayed in the console. If UIDPLUS extension is supported, it's used. Otherwise, the application obtains the UID value downloading the status of Inbox folder prior to making upload.

[C#]
using System;
using MailBee;
using MailBee.ImapMail;
using MailBee.Mime;

class Sample
{
    static void Main(string[] args)
    {
        Imap imp = new Imap();

        // Connect to the server and log in the account.
        imp.Connect("mail.server.com");
        imp.Login("jdoe", "secret");

        // Load the message from C:\Temp\message.eml file.
        MailMessage msg = new MailMessage();
        msg.LoadMessage(@"C:\Temp\message.eml");

        // Prepare the object that will receive upload results.
        UidPlusResult res = new UidPlusResult();

        long uid = 0;

        if (imp.GetExtension("UIDPLUS") == null)
        {
            FolderStatus status = imp.GetFolderStatus("Inbox");
            uid = status.UidNext;
        }

        // Upload the message and fill res with upload results.
        imp.UploadMessage(msg, "Inbox",
            MessageFlagSet.SystemFlagsToString(
            SystemMessageFlags.Seen | SystemMessageFlags.Flagged),
            "12-Apr-2006 19:30:00 +0100", true, res);

        if (res.IsSupported)
        {
            Console.WriteLine("UID of the uploaded message is " +
                res.DestUidString + ", UIDPLUS supported.");
        }
        else
        {
            Console.WriteLine("UID of the uploaded message is " +
                uid.ToString() + ", UIDPLUS not supported.");
        }

        // Disconnect from the server.
        imp.Disconnect();
    }
}

[Visual Basic]
Imports System
Imports MailBee
Imports MailBee.ImapMail
Imports MailBee.Mime

Module Sample
    Sub Main()
        Dim imp As New Imap

        ' Connect to the server, login and select inbox.
        imp.Connect("mail.domain.com")
        imp.Login("jdoe", "secret")

        ' Load the message from C:\Temp\message.eml file.
        Dim msg As New MailMessage
        msg.LoadMessage("C:\Temp\message.eml")

        ' Prepare the object that will receive upload results.
        Dim res As New UidPlusResult

        Dim uid As Long = 0

        If Not imp.GetExtension("UIDPLUS") Is Nothing Then
            Dim status As FolderStatus = imp.GetFolderStatus("Inbox")
            uid = status.UidNext
        End If

        ' Upload the message and fill res with upload results.
        imp.UploadMessage(msg, "Inbox", _
            MessageFlagSet.SystemFlagsToString( _
            SystemMessageFlags.Seen Or SystemMessageFlags.Flagged), _
            "12-Apr-2006 19:30:00 +0100", True, res)

        If res.IsSupported Then
            Console.WriteLine("UID of the uploaded message is " & _
             res.DestUidString & ", UIDPLUS supported.")
        Else
            Console.WriteLine("UID of the uploaded message is " & _
             uid.ToString() & ", UIDPLUS not supported.")
        End If

        ' Disconnect from the server.
        imp.Disconnect()
    End Sub
End Module

See Also

Imap Class | MailBee.ImapMail Namespace | Imap.UploadMessage Overload List | UidPlusResult

---