Imap.DownloadEnvelopes Method (String, Boolean)

Fetches message envelopes from the server.

public EnvelopeCollection DownloadEnvelopes(
string messageIndexSet,
bool indexIsUid
);

Parameters

messageIndexSet: A message sequence string containing ordinal message numbers or UIDs. Can be composed manually or using ToString.
indexIsUid: If true, messageIndexSet is treated as a sequence of UIDs; otherwise, as a sequence of ordinal message numbers.

Return Value

EnvelopeCollection object if message envelopes were downloaded successfully; otherwise, a null reference (Nothing in Visual Basic).

Remarks

Ordinal message numbers and UIDs are one-based (minimum value is 1, not 0). However, the returned EnvelopeCollection is zero-based. The developer can use MessageNumber or Uid properties to obtain ordinal message numbers and UIDs of the downloaded envelopes.

To specify multiple message numbers or UIDs in messageIndexSet, delimit them with comma (,) or use ranges (such as "5:10" which means "download messages in the range from message #5 to the message #10"). Wildcard character (*), can be used to specify range which spans till the last message in the folder. In particular, "1:*" means "download all messages in the folder". "1:*" is also declared as AllMessages constant.

Examples of valid message sequences: "1", "1:*", "1,2", "1:2", "5:10,12:45,99,101,105,141:*".

Note A message sequence string may NOT contain whitespaces. The following is INCORRECT: "1, 2, 5". The correct one is: "1,2,5".

When using a range of UIDs (indexIsUid is true), it's important to understand the number of returned messages may be LESS than the length of the range (or even zero). This is because UIDs are not continuous. For instance, if the folder contains messages with UIDs 4, 5, 6, 10, and 22, the "1,2,8:20" sequence of UIDs corresponds to a single message with UID=10.

This method fetches the following items from the IMAP server: UID, FLAGS, INTERNALDATE, RFC822SIZE, ENVELOPE. To get additional information about messages (for instance, a body structure, non-standard header fields, attachments, a message header section, etc), the developer should use other overloads of this method.

Note Due to complexity of IMAP4 responses, some servers may return badly formed FETCH responses under certain circumstances. If MailBee detects this, it raises ErrorOccurred event and sets IsValid to false. Since this is done on per-envelope basis, some Envelope objects in the returned collection may have IsValid set to false while others - to true. Anyway, the component does not throw exception when it encounters invalid envelope. This allows the application to skip invalid response and successfully receive subsequent messages.

Exceptions

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

Example

For each message in the Inbox, this sample downloads and displays the envelope information: From, Reply-To, To, CC, Subject, the date when the message was originally composed, and the date when the message was received by the server.

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

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

        imp.Connect("imap.server.com");

        imp.Login("jdoe@server.com", "secret");

        // Select Inbox folder.
        imp.SelectFolder("INBOX");

        // Download envelopes for last 10 messages in the inbox. If there are
        // less than 10 messages, we'll get envelopes for all of them. In this
        // sample, we define higher boundary of the range as imp.MessageCount
        // but we could also use "*" character for that.
        int start = imp.MessageCount - 9;
        if (start < 1)
        {
            start = 1;
        }
        EnvelopeCollection envs = imp.DownloadEnvelopes(
            start.ToString() + ":" + imp.MessageCount.ToString(), false);

        foreach (Envelope env in envs)
        {
            Console.WriteLine("Message #" + env.MessageNumber + " info:");
            if (env.IsValid)
            {
                Console.WriteLine("From: " + env.From.ToString());
                Console.WriteLine("Reply-To: " + env.ReplyTo.ToString());
                Console.WriteLine("To: " + env.To.ToString());
                Console.WriteLine("CC: " + env.Cc.ToString());
                Console.WriteLine("Subject: " + env.Subject);

                // Check if the message does not have Date: header set. 
                if (env.Date == DateTime.MinValue)
                {
                    Console.WriteLine("Composed at: " + env.Date);
                }
                else
                {
                    Console.WriteLine("Composed at: N/A");
                }

                Console.WriteLine("Received at: " + env.DateReceived);
            }
            else
            {
                Console.WriteLine("FETCH response contains some invalid data.");
            }
            Console.WriteLine("==============================================");
        }

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