Envelope Class
Represents an IMAP4 envelope of a mail message (including any other related information such as body structure, message flags, the mail message itself, etc).
Inheritance Hierarchy
SystemObject
  MailBee.ImapMailEnvelope

Namespace: MailBee.ImapMail
Assembly: MailBee.NET (in MailBee.NET.dll) Version: 12.4 build 677 for .NET 4.5
Syntax
public class Envelope

The Envelope type exposes the following members.

Methods
  NameDescription
Public methodEquals
Determines whether the specified object is equal to the current object.
(Inherited from Object.)
Protected methodFinalize
Allows an object to try to free resources and perform other cleanup operations before it is reclaimed by garbage collection.
(Inherited from Object.)
Public methodGetAllRecipients
Returns the list of all recipients of the mail message.
Public methodCode exampleGetEnvelopeItem
Returns a reference to the specified item of the FETCH response.
Public methodGetHashCode
Serves as the default hash function.
(Inherited from Object.)
Public methodGetType
Gets the Type of the current instance.
(Inherited from Object.)
Public methodGetUtf7DecodedGmailLabels
Gets the list of Gmail-specific labels of the message decoded from UTF-7M encoding.
Public methodHasSystemFlag
Checks if the message has a certain system flag set.
Protected methodMemberwiseClone
Creates a shallow copy of the current Object.
(Inherited from Object.)
Public methodToString
Returns a string that represents the current object.
(Inherited from Object.)
Top
Properties
  NameDescription
Public propertyBcc
Gets EmailAddressCollection object representing "BCC:" recipients of the message.
Public propertyBodyStructure
Gets the information about structure of the message.
Public propertyCc
Gets EmailAddressCollection object representing "CC:" recipients of the message.
Public propertyDate
Gets the date and time when the message was composed.
Public propertyDateReceived
Gets the date and time when the message was received by the mail server.
Public propertyDatesAsUtc
Indicates if MailBee should return date and time according to UTC standard.
Public propertyExtraHeaders
Gets a collection of additional message headers which have been explicitly requested from the server.
Public propertyFlags
Gets MessageFlagSet object containing system and custom flags of the message.
Public propertyFrom
Gets EmailAddress object representing "From:" field of the message.
Public propertyGmailLabels
Gets the list of Gmail-specific labels associated with the message.
Public propertyGmailMessageID
Gets the Gmail-specific message-id.
Public propertyGmailThreadID
Gets the Gmail-specific thread-id.
Public propertyInReplyTo
Gets the value of "In-Reply-To" header of the message.
Public propertyIsValid
Indicates if the envelope data has been successfully parsed.
Public propertyMessageID
Gets the value of "Message-ID" header of the message.
Public propertyMessageNumber
Gets the ordinal number of the message in the folder.
Public propertyMessagePreview
Gets the entire or partial mail message.
Public propertyReplyTo
Gets EmailAddress object representing "Reply-To:" field of the message.
Public propertySafeMode
Gets or sets whether empty values instead of a null reference (Nothing in Visual Basic) should be returned when the corresponding fields are not available in the data received from the server.
Public propertySender
Gets EmailAddress object representing the information about the actual sender of the message.
Public propertySize
Gets the length of the entire message (in bytes) on the mail server.
Public propertySubject
Gets the subject line of the message.
Public propertyTo
Gets EmailAddressCollection object representing "To:" recipients of the message.
Public propertyUid
Gets UID (Unique-ID) assigned to the message in the folder on the mail server.
Top
Remarks

An instance of this class represents the information about the mail message returned by the IMAP4 server in a single FETCH response. This may contain information about an IMAP4 envelope (which is a collection of common properties of a mail message such as "Subject:", "From:", "To:", etc), a body structure of the mail message, the mail message itself, its flags, ordinal message number, UID, and size, the date when the message was received by the IMAP4 server, and other message attributes including user-specified ones.

MailBee allows the developer to specify which attributes/parts of mail messages must be downloaded resulting in a greater flexibility and smaller network traffic (unnecessary items are not downloaded).

All methods of Imap object which return MailMessage or MailMessageCollection objects actually download envelopes and then extract mail messages from MessagePreview property of Envelope object.

Note Note
Due to complexity of the IMAP4 protocol, many IMAP4 server implementations cannot always produce correct FETCH responses. If MailBee detects the particular FETCH response cannot be parsed, it raises ErrorOccurred event for this response, and sets IsValid property for the corresponding response to false. No exception is thrown, however.
Most fields of the envelope may be missing (if they were not requested from the server or they are missing in the message itself). For instance, if the message has no subject, Subject property may return a null reference (Nothing in Visual Basic). To make using Envelope object easier, MailBee returns empty values instead of null references by default. To force MailBee return a null reference for a missing field, the developer should set SafeMode to false.
Examples
This sample downloads essential information about the messages in the inbox (such as IMAP4 envelope, date of receiving by the server, flags, and size), and its body structure. The messages themselves are not downloaded. The body structure information is used to count attachments of the message (this approach is more reliable than downloading message header and relying on HasAttachments property which might not be 100% correct). To notify user about particular envelopes which cannot be parsed, ErrorOccurred event handler is used.
using System;
using MailBee;
using MailBee.ImapMail;

class Sample
{
    // ErrorOccurred event handler
    private static void OnErrorOccurred(object sender, ErrorEventArgs e)
    {
        // Filter only those errors which correspond to envelopes which cannot be parsed.
        MailBeeImapInvalidEnvelopeException ex =
            e.Reason as MailBeeImapInvalidEnvelopeException;

        if (ex != null)
        {
            Console.WriteLine("WARNING: IMAP response for message #" +
                ex.InvalidEnvelope.MessageNumber + " is incorrect.");
        }
}

    // The actual code
    static void Main(string[] args)
    {
        Imap imp = new Imap();

        // Attach ErrorOccurred event handler.
        imp.ErrorOccurred += new ErrorEventHandler(OnErrorOccurred);

        // Get to inbox.
        imp.Connect("imap.domain.com");
        imp.Login("jdoe", "secret");
        imp.SelectFolder("Inbox");

        // Get envelopes, body structures, message flags, etc for all messages in the inbox.
        EnvelopeCollection envelopes = imp.DownloadEnvelopes(
            Imap.AllMessages, false, EnvelopeParts.MailBeeEnvelope | EnvelopeParts.BodyStructure, 0);

        // Demonstrate that we can work with downloaded envelopes even in offline mode.
        imp.Disconnect();

        foreach (Envelope envelope in envelopes)
        {
            if (envelope.IsValid)
            {
                Console.WriteLine("Message #" + envelope.MessageNumber +
                    ", Received at: " + envelope.DateReceived + ", Created at: " + envelope.Date);
                Console.WriteLine("  Flags: " + envelope.Flags.ToString());
                Console.WriteLine("  From: " + envelope.From.ToString());
                Console.WriteLine("  To: " + envelope.To.ToString());
                Console.WriteLine("  Subject: " + envelope.Subject);
                System.Text.StringBuilder strBuffer = new System.Text.StringBuilder();
                ImapBodyStructureCollection parts = envelope.BodyStructure.GetAllParts();
                foreach (ImapBodyStructure part in parts)
                {
                    // Detect if this part is attachment.
                    if ((part.Disposition != null && part.Disposition.ToLower() == "attachment") ||
                        (part.Filename != null && part.Filename != string.Empty) ||
                        (part.ContentType != null && part.ContentType.ToLower() == "message/rfc822"))
                    {
                        string filename;
                        if (part.Filename != null && part.Filename.Length > 0)
                        {
                            filename = part.Filename;
                        }
                        else
                        {
                            filename = "untitled";
                        }

                        // Important: Size property returns the length of part data in encoded form
                        // (such as base64). There is no way to learn the exact length unless to
                        // download the entire message. However, you may improve precision by examining
                        // MailEncodingName property value. If it's "base64", decoded data is about 70%
                        // in size of mail-encoded data. However, it's hard to estimate if it's
                        // "quoted-printable" because decoded size/encoded size ratio highly depends on
                        // the actual data contents in this case. Fortunately, "quoted-printable" is
                        // quite rarely used for attachments. If MailEncodingName is "", "binary", "7bit",
                        // or "8bit", then the data is not encoded, and Size property strictly matches
                        // the actual data length.
                        strBuffer.Append("[" + filename + " of approx. " + part.Size + " bytes]");
                    }
                }
                if (strBuffer.Length > 0)
                {
                    Console.WriteLine("  Attachments: " + strBuffer.ToString());
                }
                else
                {
                    Console.WriteLine("  Attachments: none");
                }
            }
            else
            {
                Console.WriteLine("Could not parse envelope for message #" + envelope.MessageNumber);
            }
        }
    }
}
See Also