IMAP4 Commands, Overview
version 2003 (Modified)
The set of IMAP commands enables your database to access and manipulate electronic mail messages over an IMAP electronic mail server and to retrieve electronic messages from your IMAP server. IMAP commands are compliant with the Internet Message Access Protocol, Version 4 revision 1 (IMAP4rev1), defined by rfc 2060. IMAP4rev1 allows the managing of remote message folders, called "mailboxes", in a way that is functionally similar to local mailboxes.
IMAP commands include operations to create, delete and rename mailboxes; check for new messages; permanently remove messages; set and clear message flags; search messages; and retrieve selective message parts.
Terminology
"Connection" refers to the entire sequence of IMAP client/server interaction from the initial network connection (IMAP_Login) until the end of the selection (IMAP_Logout).
"Session" refers to the sequence of client/server interaction from the moment a mailbox is selected (IMAP_SetCurrentMB) until the end of the selection (IMAP_SetCurrentMB, IMAP_CloseCurrentMB) or until the connection is closed (IMAP_Logout).
IMAP Connection Overview
• Initializing TCP communication: IT_MacTCPInit (the IT_PPPConnect command must be called before IT_MacTCPInit in the event of a PPP connection).
• Opening a connection: IMAP_Login
• Managing mailboxes: List, create, delete, rename, subscribe/unsubscribe, and/or get status parameters.
• Opening a session by defining the current working mailbox: IMAP_SetCurrentMB.
Once the current mailbox is set, you can manage messages for it.
• Managing messages: List, download or delete messages; list message flags; modify message flags; copy to another mailbox; search and retrieve e-mail parts without any downloading, etc.
• Once you are finished working with the current mailbox messages, you can close the session or open a new one by setting another current mailbox. In any case, the IMAP server will permanently update its messages. For instance, it will delete all messages with the \Deleted flag set.
• Once you are finished, you should logout. Closing a connection: IMAP_Logout.
• Other operations: Preference settings, capability, check connection, and reset any inactivity auto-logout timer on the IMAP server.
IMAP Command Themes
The IMAP-related commands are divided into two sections: IC IMAP Review Mail and IC Downloaded Mail. These commands have been separated to show the different methods of reading electronic mail. When reading electronic mail from an IMAP server, messages (or message information) may be imported into 4D structures (variables, fields, arrays) or downloaded to the disk. This section details the 4D Internet Commands' capacity to read messages from an IMAP server.
The need for dual message-retrieval methods is due mainly to memory constraints for actions that may download large amounts of information. For instance, a single message containing a 5-MB attachment could easily overflow the database's storage capacity. A picture or BLOB field is the only 4D structure capable of storing something of this size; however, converting a message or attachment to this format is not very efficient since accessing the picture or BLOB involves cumbersome memory requirements for the client. To resolve this problem, this section has an IMAP_Download command which transfers messages from the IMAP server to the user's hard disk.
Once imported to the disk, the "IC Downloaded Mail" section details the commands used to manipulate local files.
Mailbox mechanisms
An IMAP mailbox can be handled like a folder and may contain files and/or subfolders. Similarly, a mailbox may contain messages and/or submailboxes.
A mailbox is accessed using its complete hierarchical name. Depending on the IMAP server, each hierarchical level is separated by a hierarchy separator (a separator is returned using the IMAP_ListMBs command).
You can use the separator to create child mailboxes and to search higher or lower levels of the naming hierarchy. All children of a top-level hierarchy node use the same separator character.
Note: Messages can only be managed once the current working mailbox has been selected (IMAP_SetCurrentMB).
Each account can have one or several mailboxes.
Mailbox names are still case-sensitive; therefore, you cannot create two mailboxes with names that differ only in case.
The INBOX mailbox is a particular case: it exists in every account and is used for storing incoming messages. The INBOX is created automatically whenever an account is set up.
A user cannot remove the INBOX mailbox but may rename it. If he chooses to rename it, a new empty INBOX is immediately created. The INBOX name is never case-sensitive.
Some mailbox attributes, such as the total number of messages or new messages, may be checked even if the mailbox is not the current one.
msgNum and uniqueID
When using IMAP commands, it is important to fully understand the most frequently used parameters; more particularly, mailbox mechanisms msgNum and uniqueID.
msgNum is the number of a message in the mailbox at the time the IMAP_SetCurrentMB command is executed.
Once a current mailbox is selected, messages in the mailbox are assigned numbers starting from 1 up to the total number of items in the mailbox. Numbers are assigned based on the order that the messages were received in the mailbox with 1 being the oldest. The numbers assigned to messages are only valid from the moment you select the current working mailbox (IMAP_SetCurrentMB) until it is closed (IMAP_CloseCurrentMB, IMAP_SetCurrentMB or IMAP_Logout).
When the mailbox is closed, all messages marked for deletion will be removed.
When the user logs back onto the IMAP server, the current messages in the mailbox will once again be numbered from 1 to X. For instance, if there are 10 messages in the mailbox, and messages 1 to 5 are deleted, when the user reopens the mailbox, the former messages 6 to 10 will have been re-numbered 1 to 5.
For instance, consider the example below: You log on to an IMAP server and obtain the following list of messages:
| msgNum | uniqueID | Date | From | Subject |
| 1 | 10005 | 1 Jul 2001 ... | [email protected] | Sales lead... |
| 2 | 10008 | 1 Jul 2001 ... | [email protected] | Site-License order |
| 3 | 10012 | 3 Jul 2001 ... | [email protected] | Lunch anyone? |
| 4 | 20000 | 4 Jul 2002 ... | [email protected] | Your wife called... |
| 5 | 20001 | 4 Jul 2002 ... | [email protected] | FedEx tracking |
During this session, you delete messages number 3 and 4. When you close the current working mailbox, the requested deletions are made. When you log back onto the server, your message list will be re-numbered as follows:
| msgNum | uniqueID | Date | From | Subject |
| 1 | 10005 | 1 Jul 2001 ... | [email protected] | Sales lead... |
| 2 | 10008 | 1 Jul 2001 ... | [email protected] | Site-License order |
| 3 | 20001 | 4 Jul 2002 ... | [email protected] | FedEx tracking |
msgNum is not a static value and will vary from one session to another. It will change in relation to other messages in the mailbox at the time the current working mailbox is selected.
However , the uniqueID is a unique number, assigned to the message by the IMAP server in a strictly ascending order. As each message is added to the mailbox, it is assigned a higher ID than the previously added message(s).
Unfortunately, IMAP servers do not use the uniqueID as the primary reference for their messages. When using IMAP commands you will need to specify the msgNum as the reference for messages on the server. Developers may need to be careful when developing solutions which import message references into a database, while leaving the message body itself on the server.
Recommendations
Since the whole point of IMAP is interoperability, and since the latter cannot be tested in a vacuum, the final recommendation is "Test for EVERYTHING." Therefore, test your client against every server you can get an account on.
For more information, please check out the following sites:
• IMAP Products and Services: http://www.imap.org/products.html
• MailConnect: http://www.imc.org/imc-mailconnect.
POP3 and IMAP4 commands comparison
| Login | Exactly equiv | No POP parameter for IMAP |
| VerifyID | Exactly equiv | |
| Delete | Exactly equiv | IMAP commands delete in real time. POP3 waits for |
| POP3_Logout to remove messages permanently. | ||
| IMAP_SetFlags with \Deleted flag allows you to | ||
| obtain the same result as the POP3_Delete command | ||
| Logout | Exactly equiv | |
| SetPrefs | Exactly equiv | No attachFolder for IMAP, |
| POP3 attachFolder has become optional | ||
| GetPrefs | Exactly equiv | See attachFolder note in SetPrefs |
| MsgLstInfo | Exactly equiv | |
| MsgInfo | Exactly equiv | |
| MsgLst | Exactly equiv | |
| UIDToMsgNum | Exactly equiv | IMAP msgUID is a Longint, POP3 msgUID is a string |
| Download | Exactly equiv | |
| POP3_Reset | No direct equiv | Need combination of IMAP_Search on |
| \Deleted flags and IMAP_SetFlags to | ||
| remove the \Deleted flag | ||
| POP3_BoxInfo | No direct equiv | Need combination of IMAP_SetCurrentMB |
| &IMAP_MsgLstInfo commands | ||
| IMAP_ MsgNumToUID | No direct equiv | |
| GetMessage | Almost Equiv | IMAP is more powerful since it allows you |
| to choose one additional msgPart which is | ||
| "only body" | ||
| POP3_Charset | No Equiv | IMAP automatically manages charset |
| IMAP_Capability | No Equiv | Specific to IMAP protocol |
| IMAP_ListMBs | No Equiv | Specific to IMAP protocol |
| IMAP_GetMBStatus | No Equiv | Specific to IMAP protocol |
| IMAP_SetCurrentMB | No Equiv | Specific to IMAP protocol |
| IMAP_GetCurrentMB | No Equiv | Specific to IMAP protocol |
| IMAP_CloseCurrentMB | No Equiv | Specific to IMAP protocol |
| IMAP_CopyToMB | No Equiv | Specific to IMAP protocol |
| IMAP_SubscribeMB | No Equiv | Specific to IMAP protocol |
| IMAP_CreateMB | No Equiv | Specific to IMAP protocol |
| IMAP_DeleteMB | No Equiv | Specific to IMAP protocol |
| IMAP_RenameMB | No Equiv | Specific to IMAP protocol |
| IMAP_SetFlags | No Equiv | Specific to IMAP protocol |
| IMAP_GetFlags | No Equiv | Specific to IMAP protocol |
| IMAP_Search | No Equiv | Specific to IMAP protocol |
| IMAP_MsgFetch | No Equiv | Specific to IMAP protocol |
Notes:
• IMAP and POP3 servers: in the case of the IMAP server, do not type msgID the same way since msgID is a Long Integer.
• Deletion does not work in exactly the same way between POP3 and IMAP protocols. IMAP_Delete removes messages in real time. To get the same result as POP3_Delete, use the IMAP_SetFlags to set the \Deleted flag; to get the same result as POP3_Reset, use the IMAP_SetFlags to retrieve the \Deleted flags.
• For greater flexibility, 4D Internet commands let you pass a POP3, IMAP or FTP connection reference directly to low-level TCP commands and vice versa. For more information, refer to the Low Level Routines, Overview section