IMAP IDLE: IMAP4 IDLE command
A command that lets an IMAP client wait while the server pushes mailbox updates in real time.
Leiba, B., "IMAP4 IDLE command", RFC 2177, DOI 10.17487/RFC2177, June 1997, <https://www.rfc-editor.org/info/rfc2177>.
@misc{rfc2177,
series = {Request for Comments},
number = 2177,
howpublished = {RFC 2177},
publisher = {RFC Editor},
doi = {10.17487/RFC2177},
url = {https://www.rfc-editor.org/info/rfc2177},
author = {B. Leiba},
title = {{IMAP4 IDLE command}},
pagetotal = 4,
year = 1997,
month = jun,
} RFC text
Contents
Network Working Group B. Leiba
Request for Comments: 2177 IBM T.J. Watson Research Center
Category: Standards Track June 1997
IMAP4 IDLE command
Status of this Memo
This document specifies an Internet standards track protocol for the
Internet community, and requests discussion and suggestions for
improvements. Please refer to the current edition of the "Internet
Official Protocol Standards" (STD 1) for the standardization state
and status of this protocol. Distribution of this memo is unlimited.
1. Abstract
The Internet Message Access Protocol [IMAP4] requires a client to
poll the server for changes to the selected mailbox (new mail,
deletions). It's often more desirable to have the server transmit
updates to the client in real time. This allows a user to see new
mail immediately. It also helps some real-time applications based on
IMAP, which might otherwise need to poll extremely often (such as
every few seconds). (While the spec actually does allow a server to
push EXISTS responses aysynchronously, a client can't expect this
behaviour and must poll.)
This document specifies the syntax of an IDLE command, which will
allow a client to tell the server that it's ready to accept such
real-time updates.
2. Conventions Used in this Document
In examples, "C:" and "S:" indicate lines sent by the client and
server respectively.
The key words "MUST", "MUST NOT", "SHOULD", "SHOULD NOT", and "MAY"
in this document are to be interpreted as described in RFC 2060
[IMAP4].
3. Specification
IDLE Command
Arguments: none
Responses: continuation data will be requested; the client sends
the continuation data "DONE" to end the command
Result: OK - IDLE completed after client sent "DONE"
NO - failure: the server will not allow the IDLE
command at this time
BAD - command unknown or arguments invalid
The IDLE command may be used with any IMAP4 server implementation
that returns "IDLE" as one of the supported capabilities to the
CAPABILITY command. If the server does not advertise the IDLE
capability, the client MUST NOT use the IDLE command and must poll
for mailbox updates. In particular, the client MUST continue to be
able to accept unsolicited untagged responses to ANY command, as
specified in the base IMAP specification.
The IDLE command is sent from the client to the server when the
client is ready to accept unsolicited mailbox update messages. The
server requests a response to the IDLE command using the continuation
("+") response. The IDLE command remains active until the client
responds to the continuation, and as long as an IDLE command is
active, the server is now free to send untagged EXISTS, EXPUNGE, and
other messages at any time.
The IDLE command is terminated by the receipt of a "DONE"
continuation from the client; such response satisfies the server's
continuation request. At that point, the server MAY send any
remaining queued untagged responses and then MUST immediately send
the tagged response to the IDLE command and prepare to process other
commands. As in the base specification, the processing of any new
command may cause the sending of unsolicited untagged responses,
subject to the ambiguity limitations. The client MUST NOT send a
command while the server is waiting for the DONE, since the server
will not be able to distinguish a command from a continuation.
The server MAY consider a client inactive if it has an IDLE command
running, and if such a server has an inactivity timeout it MAY log
the client off implicitly at the end of its timeout period. Because
of that, clients using IDLE are advised to terminate the IDLE and
re-issue it at least every 29 minutes to avoid being logged off.
This still allows a client to receive immediate mailbox updates even
though it need only "poll" at half hour intervals.
Example: C: A001 SELECT INBOX
S: * FLAGS (Deleted Seen)
S: * 3 EXISTS
S: * 0 RECENT
S: * OK [UIDVALIDITY 1]
S: A001 OK SELECT completed
C: A002 IDLE
S: + idling
...time passes; new mail arrives...
S: * 4 EXISTS
C: DONE
S: A002 OK IDLE terminated
...another client expunges message 2 now...
C: A003 FETCH 4 ALL
S: * 4 FETCH (...)
S: A003 OK FETCH completed
C: A004 IDLE
S: * 2 EXPUNGE
S: * 3 EXISTS
S: + idling
...time passes; another client expunges message 3...
S: * 3 EXPUNGE
S: * 2 EXISTS
...time passes; new mail arrives...
S: * 3 EXISTS
C: DONE
S: A004 OK IDLE terminated
C: A005 FETCH 3 ALL
S: * 3 FETCH (...)
S: A005 OK FETCH completed
C: A006 IDLE
4. Formal Syntax
The following syntax specification uses the augmented Backus-Naur
Form (BNF) notation as specified in [RFC-822] as modified by [IMAP4].
Non-terminals referenced but not defined below are as defined by
[IMAP4].
command_auth ::= append / create / delete / examine / list / lsub /
rename / select / status / subscribe / unsubscribe
/ idle
;; Valid only in Authenticated or Selected state
idle ::= "IDLE" CRLF "DONE"
5. References
[IMAP4] Crispin, M., "Internet Message Access Protocol - Version
4rev1", RFC 2060, December 1996.
6. Security Considerations
There are no known security issues with this extension.
7. Author's Address
Barry Leiba
IBM T.J. Watson Research Center
30 Saw Mill River Road
Hawthorne, NY 10532
Email: leiba@watson.ibm.com
ISO Plain Language
On this page
§1Why IMAP Clients Had to Poll
The base IMAP4 protocol (RFC 2060) requires a client to poll the server for changes to the selected mailbox, such as new mail or deletions. Users would rather see new mail immediately, and real-time applications built on IMAP might otherwise need to poll every few seconds.
The RFC notes that the base specification does allow a server to push EXISTS responses asynchronously, but a client cannot expect that behaviour and must poll. The IDLE command lets a client tell the server that it is ready to accept such real-time updates.
Asking the mail server over and over whether anything is new is wasteful and slow to notice changes. IDLE lets the client say once that it is listening and then wait quietly.
§3How IDLE Works
IDLE takes no arguments. A client may use it only if the server lists IDLE in its CAPABILITY response; if the server does not advertise it, the client MUST NOT use IDLE and must poll. The server answers with a continuation (+) response, and from then on it is free to send untagged EXISTS, EXPUNGE and other messages at any time.
The client ends the command by sending the continuation data DONE, which satisfies the server's continuation request. The server MAY send any queued untagged responses and then MUST immediately send the tagged response to IDLE and be ready for other commands. The client MUST NOT send any other command while the server is waiting for DONE, because the server could not tell a command from a continuation. The possible results are OK after DONE, NO when the server will not allow IDLE now, and BAD.
You may only use the command if the server offers it. Once you send it, the server may tell you about changes whenever it likes, and it can only tell your command apart from the word DONE, so you must not type anything else until you send DONE.
- A002 IDLE
- + idling
- * 4 EXISTSNew mail arrives while idling.
- DONE
- A002 OK IDLE terminated
§3.1Timeouts and the 29-Minute Rule
A server MAY consider a client that has an IDLE command running to be inactive, and if it has an inactivity timeout it MAY log the client off at the end of that period. Because of that, clients using IDLE are advised to terminate it and re-issue it at least every 29 minutes.
This still lets a client receive immediate mailbox updates even though it only needs to check in at half-hour intervals.
A server may drop a silent client. To stay connected, a client should quiet-and-wait again at least every 29 minutes, which is far less often than polling every few seconds.
§4Example Session and Syntax
The RFC's example selects INBOX, issues A002 IDLE, and gets a + idling continuation response. New mail arrives as an untagged EXISTS response for message 4, then the client sends DONE and the server replies A002 OK IDLE terminated. Later, an untagged EXPUNGE response for message 2, caused by another client's deletion, arrives the same way while the client is idling again.
The formal syntax adds idle to the commands valid in the Authenticated or Selected state, defined simply as "IDLE" CRLF "DONE". The RFC says there are no known security issues with this extension.
The example shows the server announcing new mail and a deletion all by itself while the client waits, then the client saying DONE to end the wait.