ImapUploadMessage Method (MailMessage, String, String, String, Boolean, UidPlusResult)
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.

Namespace: MailBee.ImapMail
Assembly: MailBee.NET (in MailBee.NET.dll) Version: 11.2.0 build 590 for .NET 4.5
Syntax
public bool UploadMessage(
	MailMessage msg,
	string folderName,
	string flags,
	string dateTimeString,
	bool batchMode,
	UidPlusResult result
)

Parameters

msg
Type: MailBee.MimeMailMessage
A reference to the MailMessage object representing the message to be uploaded.
folderName
Type: SystemString
The full name of the folder to upload the message to.
flags
Type: SystemString
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
Type: SystemString
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
Type: SystemBoolean
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
Type: MailBee.ImapMailUidPlusResult
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

Type: Boolean
true if the message was uploaded successfully; otherwise, false.
Exceptions
ExceptionCondition
MailBeeExceptionAn error occurred and ThrowExceptions is true.
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(String) method, and then call UploadMessage(MailMessage, String, String, String, Boolean, UidPlusResult) passing a reference to this MailMessage object. There is no extra overhead on parsing the message since LoadMessage(String) 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(MailMessage, String, String, String, Boolean, UidPlusResult) 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(SystemMessageFlags) 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(MailMessage, String, String, String, Boolean, UidPlusResult) method always upload messages in batch mode if LITERAL+ is supported.

When result is specified and the server supports and correctly implements UIDPLUS extension, UploadMessage(MailMessage, String, String, String, Boolean, UidPlusResult) method will set the supplied UidPlusResult object properties as below:

PropertyValue
IsValidtrue
IsSupportedtrue
SrcUidsnull
SrcUidStringnull
DestUidsThe UidCollection object containing a single value of the UID assigned to the uploaded message.
DestUidStringThe string containing the UID assigned to the uploaded message.
DestUidValidityThe UIDVALIDITY of the folder the message was uploaded to.

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(String) method. However, the application must call GetFolderStatus(String) method BEFORE making upload (see the sample).

The developer can also try to avoid calling GetFolderStatus(String) 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).

Some servers claim they support UIDPLUS but in fact there is no UIDPLUS data in the response (of the data has incorrect format). IsSupported will still be true but IsValid will be false in this case.

Examples
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.
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();
    }
}
See Also