TIdIMAP4.ExamineMailBox Method

Selects a mailbox for read-only access.

Pascal

function ExamineMailBox(
    const AMBName: String; 
    AMB: TIdMailBox
): Boolean;

Parameters

Parameters	Description
AMBName	Mailbox name to use accessed on the IMAP4 server.
AMB	Mailbox to be filled with the retrieved message values.

Returns

Boolean - True on success.

Description

ExamineMailBox is a Boolean function in TIdIMAP4 used to select the mailbox specified in AMBName for read-only access. Messages and Flags are retrieved from the mailbox and stored in the TIdMailBox instance specified in AMB. ExamineMailBox returns the same output as SelectMailBox, except for the read-only attribute applied to the mailbox, flags, and messages.

ExamineMailBox requires that the value of ConnectionState contain either csAuthenticated or csSelected, or an EIdConnectionStateError exception will be raised.

ExamineMailBox calls SendCmd using the IMAP EXAMINE command. When the numeric code in LastCmdResult contains wsOk, the text values in LastCmdResult are parsed to populate the TIdMailBox instance specified AMB.

Please note that IMAP servers are required to have an "Inbox" folder to allow them to receive email for a given user. This may or may not be case-sensitive. Your implementation may require you to create an Inbox folder if it does not already exist.

Use caustion when choosing the characters used in mailbox names. Different IMAP servers may allow, and interpret differently, various characters, which is allowed within the IMAP specification. Characters such as ~ / and . may have special meaning in the IMAP servers context, and may produce unexpected results. In practice, some IMAP servers may be case-sensitive and others not. It is recommended that you only use the characters A-Z and 0-9 and that you program to allow for case sensitivity or insensitivity, as applicable. Note that, in general, IdIMAP4 adds double-quotes around mailbox names, which allows the use of spaces in mailbox names, but also note that a perticular IMAP server may not allow spaces (this functionality is necessary to allow IdIMAP4 deal with pre-existing mailboxes that include spaces).

ExamineMailBox returns True on successful completion of the method, or false when the response code is not IMAP_OK or an exception occurs.