1 ../imapserver/server.go:141
2
3
4
5
6
7Network Working Group M. Crispin
8Request for Comments: 4315 December 2005
9Obsoletes: 2359
10Category: Standards Track
11
12
13 Internet Message Access Protocol (IMAP) - UIDPLUS extension
14
15Status of This Memo
16
17 This document specifies an Internet standards track protocol for the
18 Internet community, and requests discussion and suggestions for
19 improvements. Please refer to the current edition of the "Internet
20 Official Protocol Standards" (STD 1) for the standardization state
21 and status of this protocol. Distribution of this memo is unlimited.
22
23Copyright Notice
24
25 Copyright (C) The Internet Society (2005).
26
27Abstract
28
29 The UIDPLUS extension of the Internet Message Access Protocol (IMAP)
30 provides a set of features intended to reduce the amount of time and
31 resources used by some client operations. The features in UIDPLUS
32 are primarily intended for disconnected-use clients.
33
341. Introduction and Overview
35
36 The UIDPLUS extension is present in any IMAP server implementation
37 that returns "UIDPLUS" as one of the supported capabilities to the
38 CAPABILITY command.
39
40 The UIDPLUS extension defines an additional command. In addition,
41 this document recommends new status response codes in IMAP that
42 SHOULD be returned by all server implementations, regardless of
43 whether or not the UIDPLUS extension is implemented.
44
45 The added facilities of the features in UIDPLUS are optimizations;
46 clients can provide equivalent functionality, albeit less
47 efficiently, by using facilities in the base protocol.
48
491.1. Conventions Used in This Document
50
51 In examples, "C:" and "S:" indicate lines sent by the client and
52 server, respectively.
53
54
55
56
57
58Crispin Standards Track [Page 1]
59
60RFC 4315 IMAP - UIDPLUS Extension December 2005
61
62
63 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
64 "SHOULD", "SHOULD NOT", "MAY", and "OPTIONAL" in this document are to
65 be interpreted as described in [KEYWORDS].
66
67 A "UID set" is similar to the [IMAP] sequence set; however, the "*"
68 value for a sequence number is not permitted.
69
702. Additional Commands
71
72 The following command definition is an extension to [IMAP] section
73 6.4.
74
752.1. UID EXPUNGE Command 9051:4775 7162:1873 ../imapserver/server.go:3158
76
77 Arguments: sequence set
78
79 Data: untagged responses: EXPUNGE
80
81 Result: OK - expunge completed
82 NO - expunge failure (e.g., permission denied)
83 BAD - command unknown or arguments invalid
84
85 The UID EXPUNGE command permanently removes all messages that both
86 have the \Deleted flag set and have a UID that is included in the
87 specified sequence set from the currently selected mailbox. If a
88 message either does not have the \Deleted flag set or has a UID
89 that is not included in the specified sequence set, it is not
90 affected.
91
92 This command is particularly useful for disconnected use clients.
93 By using UID EXPUNGE instead of EXPUNGE when resynchronizing with
94 the server, the client can ensure that it does not inadvertantly
95 remove any messages that have been marked as \Deleted by other
96 clients between the time that the client was last connected and
97 the time the client resynchronizes.
98
99 If the server does not support the UIDPLUS capability, the client
100 should fall back to using the STORE command to temporarily remove
101 the \Deleted flag from messages it does not want to remove, then
102 issuing the EXPUNGE command. Finally, the client should use the
103 STORE command to restore the \Deleted flag on the messages in
104 which it was temporarily removed.
105
106 Alternatively, the client may fall back to using just the EXPUNGE
107 command, risking the unintended removal of some messages.
108
109
110
111
112
113
114Crispin Standards Track [Page 2]
115
116RFC 4315 IMAP - UIDPLUS Extension December 2005
117
118
119 Example: C: A003 UID EXPUNGE 3000:3002
120 S: * 3 EXPUNGE
121 S: * 3 EXPUNGE
122 S: * 3 EXPUNGE
123 S: A003 OK UID EXPUNGE completed
124
1253. Additional Response Codes
126
127 The following response codes are extensions to the response codes
128 defined in [IMAP] section 7.1. With limited exceptions, discussed
129 below, server implementations that advertise the UIDPLUS extension
130 SHOULD return these response codes.
131
132 In the case of a mailbox that has permissions set so that the client
133 can COPY or APPEND to the mailbox, but not SELECT or EXAMINE it, the
134 server SHOULD NOT send an APPENDUID or COPYUID response code as it
135 would disclose information about the mailbox.
136
137 In the case of a mailbox that has UIDNOTSTICKY status (as defined
138 below), the server MAY omit the APPENDUID or COPYUID response code as
139 it is not meaningful.
140
141 If the server does not return the APPENDUID or COPYUID response
142 codes, the client can discover this information by selecting the
143 destination mailbox. The location of messages placed in the
144 destination mailbox by COPY or APPEND can be determined by using
145 FETCH and/or SEARCH commands (e.g., for Message-ID or some unique
146 marker placed in the message in an APPEND).
147
148 APPENDUID
149
150 Followed by the UIDVALIDITY of the destination mailbox and the UID
151 assigned to the appended message in the destination mailbox,
152 indicates that the message has been appended to the destination
153 mailbox with that UID.
154
155 If the server also supports the [MULTIAPPEND] extension, and if
156 multiple messages were appended in the APPEND command, then the
157 second value is a UID set containing the UIDs assigned to the
158 appended messages, in the order they were transmitted in the
159 APPEND command. This UID set may not contain extraneous UIDs or
160 the symbol "*".
161
162 Note: the UID set form of the APPENDUID response code MUST NOT
163 be used if only a single message was appended. In particular,
164 a server MUST NOT send a range such as 123:123. This is
165 because a client that does not support [MULTIAPPEND] expects
166 only a single UID and not a UID set.
167
168
169
170Crispin Standards Track [Page 3]
171
172RFC 4315 IMAP - UIDPLUS Extension December 2005
173
174
175 UIDs are assigned in strictly ascending order in the mailbox
176 (refer to [IMAP], section 2.3.1.1) and UID ranges are as in
177 [IMAP]; in particular, note that a range of 12:10 is exactly
178 equivalent to 10:12 and refers to the sequence 10,11,12.
179
180 This response code is returned in a tagged OK response to the
181 APPEND command.
182
183 COPYUID 9051:6881 ../imapserver/server.go:3474
184
185 Followed by the UIDVALIDITY of the destination mailbox, a UID set
186 containing the UIDs of the message(s) in the source mailbox that
187 were copied to the destination mailbox and containing the UIDs
188 assigned to the copied message(s) in the destination mailbox,
189 indicates that the message(s) have been copied to the destination
190 mailbox with the stated UID(s).
191
192 The source UID set is in the order the message(s) were copied; the
193 destination UID set corresponds to the source UID set and is in
194 the same order. Neither of the UID sets may contain extraneous
195 UIDs or the symbol "*".
196
197 UIDs are assigned in strictly ascending order in the mailbox
198 (refer to [IMAP], section 2.3.1.1) and UID ranges are as in
199 [IMAP]; in particular, note that a range of 12:10 is exactly
200 equivalent to 10:12 and refers to the sequence 10,11,12.
201
202 This response code is returned in a tagged OK response to the COPY
203 command.
204
205 UIDNOTSTICKY
206
207 The selected mailbox is supported by a mail store that does not
208 support persistent UIDs; that is, UIDVALIDITY will be different
209 each time the mailbox is selected. Consequently, APPEND or COPY
210 to this mailbox will not return an APPENDUID or COPYUID response
211 code.
212
213 This response code is returned in an untagged NO response to the
214 SELECT command.
215
216 Note: servers SHOULD NOT have any UIDNOTSTICKY mail stores.
217 This facility exists to support legacy mail stores in which it
218 is technically infeasible to support persistent UIDs. This
219 should be avoided when designing new mail stores.
220
221
222
223
224
225
226Crispin Standards Track [Page 4]
227
228RFC 4315 IMAP - UIDPLUS Extension December 2005
229
230
231 Example: C: A003 APPEND saved-messages (\Seen) {297}
232 C: Date: Mon, 7 Feb 1994 21:52:25 -0800 (PST)
233 C: From: Fred Foobar <foobar@example.com>
234 C: Subject: afternoon meeting
235 C: To: mooch@example.com
236 C: Message-Id: <B27397-0100000@example.com>
237 C: MIME-Version: 1.0
238 C: Content-Type: TEXT/PLAIN; CHARSET=US-ASCII
239 C:
240 C: Hello Joe, do you think we can meet at 3:30 tomorrow?
241 C:
242 S: A003 OK [APPENDUID 38505 3955] APPEND completed
243 C: A004 COPY 2:4 meeting
244 S: A004 OK [COPYUID 38505 304,319:320 3956:3958] Done
245 C: A005 UID COPY 305:310 meeting
246 S: A005 OK No matching messages, so nothing copied
247 C: A006 COPY 2 funny
248 S: A006 OK Done
249 C: A007 SELECT funny
250 S: * 1 EXISTS
251 S: * 1 RECENT
252 S: * OK [UNSEEN 1] Message 1 is first unseen
253 S: * OK [UIDVALIDITY 3857529045] Validity session-only
254 S: * OK [UIDNEXT 2] Predicted next UID
255 S: * NO [UIDNOTSTICKY] Non-persistent UIDs
256 S: * FLAGS (\Answered \Flagged \Deleted \Seen \Draft)
257 S: * OK [PERMANENTFLAGS (\Deleted \Seen)] Limited
258 S: A007 OK [READ-WRITE] SELECT completed
259
260 In this example, A003 and A004 demonstrate successful appending and
261 copying to a mailbox that returns the UIDs assigned to the messages.
262 A005 is an example in which no messages were copied; this is because
263 in A003, we see that message 2 had UID 304, and message 3 had UID
264 319; therefore, UIDs 305 through 310 do not exist (refer to section
265 2.3.1.1 of [IMAP] for further explanation). A006 is an example of a
266 message being copied that did not return a COPYUID; and, as expected,
267 A007 shows that the mail store containing that mailbox does not
268 support persistent UIDs.
269
2704. Formal Syntax
271
272 Formal syntax is defined using ABNF [ABNF], which extends the ABNF
273 rules defined in [IMAP]. The IMAP4 ABNF should be imported before
274 attempting to validate these rules.
275
276 append-uid = uniqueid
277
278 capability =/ "UIDPLUS"
279
280
281
282Crispin Standards Track [Page 5]
283
284RFC 4315 IMAP - UIDPLUS Extension December 2005
285
286
287 command-select =/ uid-expunge
288
289 resp-code-apnd = "APPENDUID" SP nz-number SP append-uid
290
291 resp-code-copy = "COPYUID" SP nz-number SP uid-set SP uid-set
292
293 resp-text-code =/ resp-code-apnd / resp-code-copy / "UIDNOTSTICKY"
294 ; incorporated before the expansion rule of
295 ; atom [SP 1*<any TEXT-CHAR except "]">]
296 ; that appears in [IMAP]
297
298 uid-expunge = "UID" SP "EXPUNGE" SP sequence-set 9051:7125 9051:7129 ../imapserver/server.go:3160
299
300 uid-set = (uniqueid / uid-range) *("," uid-set)
301
302 uid-range = (uniqueid ":" uniqueid)
303 ; two uniqueid values and all values
304 ; between these two regards of order.
305 ; Example: 2:4 and 4:2 are equivalent.
306
307 Servers that support [MULTIAPPEND] will have the following extension
308 to the above rules:
309
310 append-uid =/ uid-set
311 ; only permitted if client uses [MULTIAPPEND]
312 ; to append multiple messages.
313
3145. Security Considerations
315
316 The COPYUID and APPENDUID response codes return information about the
317 mailbox, which may be considered sensitive if the mailbox has
318 permissions set that permit the client to COPY or APPEND to the
319 mailbox, but not SELECT or EXAMINE it.
320
321 Consequently, these response codes SHOULD NOT be issued if the client
322 does not have access to SELECT or EXAMINE the mailbox.
323
3246. IANA Considerations
325
326 This document constitutes registration of the UIDPLUS capability in
327 the imap4-capabilities registry, replacing [RFC2359].
328
3297. Normative References
330
331 [ABNF] Crocker, D. and P. Overell, "Augmented BNF for Syntax
332 Specifications: ABNF", RFC 4234, October 2005.
333
334
335
336
337
338Crispin Standards Track [Page 6]
339
340RFC 4315 IMAP - UIDPLUS Extension December 2005
341
342
343 [IMAP] Crispin, M., "INTERNET MESSAGE ACCESS PROTOCOL -
344 VERSION 4rev1", RFC 3501, March 2003.
345
346 [KEYWORDS] Bradner, S., "Key words for use in RFCs to Indicate
347 Requirement Levels", BCP 14, RFC 2119, March 1997.
348
349 [MULTIAPPEND] Crispin, M., "Internet Message Access Protocol (IMAP) -
350 MULTIAPPEND Extension", RFC 3502, March 2003.
351
3528. Informative References
353
354 [RFC2359] Myers, J., "IMAP4 UIDPLUS extension", RFC 2359, June
355 1998.
356
3579. Changes from RFC 2359
358
359 This document obsoletes [RFC2359]. However, it is based upon that
360 document, and takes substantial text from it (albeit with numerous
361 clarifications in wording).
362
363 [RFC2359] implied that a server must always return COPYUID/APPENDUID
364 data; thus suggesting that in such cases the server should return
365 arbitrary data if the destination mailbox did not support persistent
366 UIDs. This document adds the UIDNOTSTICKY response code to indicate
367 that a mailbox does not support persistent UIDs, and stipulates that
368 a UIDPLUS server does not return COPYUID/APPENDUID data when the COPY
369 (or APPEND) destination mailbox has UIDNOTSTICKY status.
370
371Author's Address
372
373 Mark R. Crispin
374 Networks and Distributed Computing
375 University of Washington
376 4545 15th Avenue NE
377 Seattle, WA 98105-4527
378
379 Phone: (206) 543-5762
380 EMail: MRC@CAC.Washington.EDU
381
382
383
384
385
386
387
388
389
390
391
392
393
394Crispin Standards Track [Page 7]
395
396RFC 4315 IMAP - UIDPLUS Extension December 2005
397
398
399Full Copyright Statement
400
401 Copyright (C) The Internet Society (2005).
402
403 This document is subject to the rights, licenses and restrictions
404 contained in BCP 78, and except as set forth therein, the authors
405 retain all their rights.
406
407 This document and the information contained herein are provided on an
408 "AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE REPRESENTS
409 OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY AND THE INTERNET
410 ENGINEERING TASK FORCE DISCLAIM ALL WARRANTIES, EXPRESS OR IMPLIED,
411 INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE
412 INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED
413 WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.
414
415Intellectual Property
416
417 The IETF takes no position regarding the validity or scope of any
418 Intellectual Property Rights or other rights that might be claimed to
419 pertain to the implementation or use of the technology described in
420 this document or the extent to which any license under such rights
421 might or might not be available; nor does it represent that it has
422 made any independent effort to identify any such rights. Information
423 on the procedures with respect to rights in RFC documents can be
424 found in BCP 78 and BCP 79.
425
426 Copies of IPR disclosures made to the IETF Secretariat and any
427 assurances of licenses to be made available, or the result of an
428 attempt made to obtain a general license or permission for the use of
429 such proprietary rights by implementers or users of this
430 specification can be obtained from the IETF on-line IPR repository at
431 http://www.ietf.org/ipr.
432
433 The IETF invites any interested party to bring to its attention any
434 copyrights, patents or patent applications, or other proprietary
435 rights that may cover technology that may be required to implement
436 this standard. Please address the information to the IETF at ietf-
437 ipr@ietf.org.
438
439Acknowledgement
440
441 Funding for the RFC Editor function is currently provided by the
442 Internet Society.
443
444
445
446
447
448
449
450Crispin Standards Track [Page 8]
451
452