Edit File: commndmt.txt
/* ======================================================================== * Copyright 1988-2006 University of Washington * * Licensed under the Apache License, Version 2.0 (the "License"); * you may not use this file except in compliance with the License. * You may obtain a copy of the License at * * http://www.apache.org/licenses/LICENSE-2.0 * * * ======================================================================== */ [I wrote this tongue-in-cheek, but there's a lot here that people who build IMAP clients should take careful note. Most existing clients violate at least one, generally several, of these commandments. These are based on known user-visible problems that occur with various commonly used clients. Put another way, behind each commandment is a plethora of user (and server administrator) complaints caused by a violator.] Ten Commandments of How to Write an IMAP client Mark Crispin 1. Thou shalt not assume that it is alright to open multiple IMAP sessions selected on the same mailbox simultaneously, lest thou face the righteous wrath of mail stores that doth not permit such access. Instead, thou shalt labor mightily, even unto having to use thy brain to thinketh the matter through, such that thy client use existing sessions that are already open. 2. Thou shalt not abuse the STATUS command by using it to check for new mail on a mailbox that you already have selected in an IMAP session; for that session hath already told thou about new mail without thy having to ask. 3. Thou shalt remember the 30 minute inactivity timeout, and remember to speak to the IMAP server before that timeout expires. If thou useth the IDLE command, thou shalt send DONE from the IDLE before 29 minutes hath passed, and issue a new IDLE. If thou maketh no use of IDLE, then thou shalt send NOOP every few minutes, and the server shalt tell you about new mail, and there will be much rejoicing in the land. 4. Thou shalt not assume that all names are both the name of a mailbox and the name of a upper level of hierarchy that contains mailboxes; lest thou face the righteous wrath of mail stores in which a mailbox is a file and a level of hierarchy is a directory. Thou shalt pay diligent attention to the \NoSelect and \NoInferiors flags, so that your users may praise you with great praise. 5. Thou shalt learn and understand the unique features of IMAP, such as the unsolicited data model, the strict ascending rule of UIDs, how UIDs map to sequence numbers, the ENVELOPE and BODYSTRUCTURE structures; so that thou may use the IMAP protocol effectively. For a POP client hacked to babble IMAP protocol is still no more than a POP client. 6. Thou shalt remember untagged data sent by the server, and when thou needest data thou shalt consult your memory before asking the server. For those who must analyze thy protocol transactions are weak of stomach, and are likely to lose their recent meal should they see thou repeatedly re-fetch static data. 7. Thou shalt labor with great effort to work within the IMAP deleted/expunge model, even if thy own model is that of a trashcan; for interoperability is paramount and a trashcan model can be done entirely in the user interface. 8. Thou shalt not fear to open multiple IMAP sessions to the server; but thou shalt use this technique with wisdom. For verily it is true; if thou doth desire to monitor continuously five mailboxes for new mail, it is better to have five IMAP sessions continuously open on the mailboxes. It is generally not good to do a succession of five SELECT or STATUS commands on a periodic basis; and it is truly wretched to open and close five sessions to do a STATUS or SELECT on a periodic basis. The cost of opening and closing a session is great, especially if that session is SSL/TLS protected; and the cost of a STATUS or SELECT can also be great. By comparison, the cost of an open session doing an IDLE or getting a NOOP every few minutes is small. Great praise shall be given to thy wisdom in doing what is less costly instead of "common sense." 9. Thou shalt not abuse subscriptions, for verily the LIST command is the proper way to discover mailboxes on the server. Thou shalt not subscribe names to the user's subscription list without explicit instructions from the user; nor shalt thou assume that only subscribed names are valid. Rather, thou shalt treat subscribed names as akin to a bookmarks, or perhaps akin to how Windows shows the "My Documents" folder -- a set of names that are separate from the hierarchy, for they are such. 10. Thou shalt use the LIST "*" wildcard only with great care. If thou doth not fully comprehend the danger of "*", thou shalt use only "%" and forget about the existance of "*". Honor these commandments, and keep them holy in thy heart, so that thy users shalt maximize their pleasure, and the server administrators shalt sing thy praises and recommend thy work as a model for others to emulate.