Imap.UploadMessage Method (MailMessage, String, String, String)

Uploads a mail message to the specified folder and assigns the specified date and flags to this message.

public bool UploadMessage(
   MailMessage msg,
   string folderName,
   string flags,
   string dateTimeString
);

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.

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 obtain the UID value assigned to the uploaded message, the developer should either examine DestUidString property of UidPlusResult object passed in res parameter of UploadMessage method (the server must support UIDPLUS capability), or obtain UidNext value calling GetFolderStatus method before making upload (this approach is compatible with all servers).

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.

Exceptions

Exception Type	Condition
MailBeeException	An error occurred and ThrowExceptions is true.

Example

This sample creates a new mail message and saves it into "Draft" folder (creating the folder if necessary) using the current datetime/timezone of the mail server. "\Draft" and non-standard "$Personal" flag are set (and the server will implicitly add "\Recent" flag).

However, it may be forbidden by the server to set non-standard flags for messages. For this purpose, we check if PermanentFlags includes CanCreate flag. If not, we set "\Draft" flag only.

Note In this sample, we do not check if "$Personal" flag is already available. Real-world applications should first check if the specified non-standard flag is already available in PermanentFlags and try to add new flag only if it's not already available.

[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.company.com");
        imp.Login("jdoe@company.com", "secret");

        // Create a new message. Assume we need to save a draft of the message.
        MailMessage msg = new MailMessage();

        // Try to select Draft folder and create it if needed.
        // We do not need to select the folder for uploading but
        // we need to check if it's permitted to use non-system flags
        // (such as "$Personal") in this folder.
        try
        {
            imp.ExamineFolder("Draft");
        }
        catch (MailBeeImapNegativeResponseException e)
        {
            if (e.CompletionResult == "NO")
            {
                imp.CreateFolder("Draft");
                imp.ExamineFolder("Draft");
            }
            else
            {
                throw;
            }
        }

        string flags = MessageFlagSet.SystemFlagsToString(SystemMessageFlags.Draft);

        // Add "$Personal" flag if it's allowed for this folder.
        if ((imp.PermanentFlags.SystemFlags & SystemMessageFlags.CanCreate) > 0)
        {
            flags += " $Personal";
        }

        // May close the folder since it's not needed any longer. This will not
        // expunge any deleted messages (which usually occurs on Close() call)
        // since we used ExamineFolder to select the folder. Unlike SelectFolder,
        // ExamineFolder selects folder in read-only mode.
        imp.Close();

        // Upload the message and assign the current datetime and timezone
        // of the server as the date of receiving the message by the server
        // (INTERNALDATE in IMAP4 terms).
        imp.UploadMessage(msg, "Draft", flags, null);

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