TIdIMAP4.RenameMailBox Method

Renames a specified mailbox on the IMAP4 server.

Pascal

function RenameMailBox(
    const AOldMBName: String; 
    const ANewMBName: String
): Boolean;

Parameters

Parameters	Description
AOldMBName	Mailbox name to be changed .
ANewMBName	New name for the mailbox.

Returns

Boolean - True on success.

Description

RenameMailBox is a Boolean function used to rename the mailbox specified in AOldMBName to the value specified in ANewMBName on the remote IMAP4 server. RenameMailBox will receive a protocol error if a mailbox with the name specified in AOldMBName does not exist, or when a mailbox with the name specified in ANewMBName already exists for the IMAP4 account.

Renaming the "INBOX" mailbox is permitted in the IMAP4 RFC, and has special behaviour. It moves all messages in INBOX to a new mailbox with the given name, leaving INBOX empty. If the server implementation supports inferior hierarchical names of INBOX, these are unaffected by a rename of INBOX. Note that the behaviour on IMAP4 servers for renaming INBOX seems to be varied in practice, and consequently renaming of the INBOX is not encouraged.

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

RenameMailBox calls SendCmd using the IMAP4 RENAME command to alter the mailbox name. RenameMailBox sets the return value to True when the server response contains the value IMAP_OK.

Please note that IMAP4 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.

WARNING:

Be careful with the characters you use for 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 IMAP4 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. Also 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 particular IMAP4 server may not allow spaces (this functionality is necessary to allow IdIMAP4 deal with pre-existing mailboxes that include spaces).