Internet Message Access Protocol (IMAP) - SAVEDATE Extension
An IMAP extension that adds a save date: the moment a message landed in its current mailbox, which cannot be faked or copied.
Bosch, S., "Internet Message Access Protocol (IMAP) - SAVEDATE Extension", RFC 8514, DOI 10.17487/RFC8514, January 2019, <https://www.rfc-editor.org/info/rfc8514>.
@misc{rfc8514,
series = {Request for Comments},
number = 8514,
howpublished = {RFC 8514},
publisher = {RFC Editor},
doi = {10.17487/RFC8514},
url = {https://www.rfc-editor.org/info/rfc8514},
author = {S. Bosch},
title = {{Internet Message Access Protocol (IMAP) - SAVEDATE Extension}},
pagetotal = 7,
year = 2019,
month = jan,
} RFC text
Contents
Internet Engineering Task Force (IETF) S. Bosch
Request for Comments: 8514 Open Xchange Oy
Category: Standards Track January 2019
ISSN: 2070-1721
Internet Message Access Protocol (IMAP) - SAVEDATE Extension
Abstract
This document adds a new capability called "SAVEDATE" to the Internet
Message Access Protocol (IMAP). It defines a new IMAP message
attribute called "save date" that, unlike the existing "internal
date" attribute, always indicates the moment at which the message was
saved in its current mailbox. The SAVEDATE capability extends the
FETCH command with the means to retrieve the save date attribute and
extends the SEARCH command to allow using the save date attribute in
searching criteria.
Status of This Memo
This is an Internet Standards Track document.
This document is a product of the Internet Engineering Task Force
(IETF). It represents the consensus of the IETF community. It has
received public review and has been approved for publication by the
Internet Engineering Steering Group (IESG). Further information on
Internet Standards is available in Section 2 of RFC 7841.
Information about the current status of this document, any errata,
and how to provide feedback on it may be obtained at
https://www.rfc-editor.org/info/rfc8514.
Copyright Notice
Copyright (c) 2019 IETF Trust and the persons identified as the
document authors. All rights reserved.
This document is subject to BCP 78 and the IETF Trust's Legal
Provisions Relating to IETF Documents
(https://trustee.ietf.org/license-info) in effect on the date of
publication of this document. Please review these documents
carefully, as they describe your rights and restrictions with respect
to this document. Code Components extracted from this document must
include Simplified BSD License text as described in Section 4.e of
the Trust Legal Provisions and are provided without warranty as
described in the Simplified BSD License.
Table of Contents
1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2
2. Conventions Used in This Document . . . . . . . . . . . . . . 3
3. Save Date Message Attribute . . . . . . . . . . . . . . . . . 3
4. IMAP Protocol Changes . . . . . . . . . . . . . . . . . . . . 4
4.1. CAPABILITY Identification . . . . . . . . . . . . . . . . 4
4.2. FETCH Command and Response Extensions . . . . . . . . . . 4
4.3. SEARCH Command Extension . . . . . . . . . . . . . . . . 4
5. Formal Syntax . . . . . . . . . . . . . . . . . . . . . . . . 5
6. Security Considerations . . . . . . . . . . . . . . . . . . . 5
7. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 6
8. Normative References . . . . . . . . . . . . . . . . . . . . 6
Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . . 7
Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 7
1. Introduction
This document extends the Internet Message Access Protocol (IMAP)
[IMAP4rev1] with a new capability called "SAVEDATE". This capability
adds a new IMAP message attribute called "save date". The save date
is the date and time at which a message was saved in the mailbox in
which it currently resides. The save date is similar to the existing
"internal date" attribute in that it is set at the time of delivery.
However, the internal date attribute can be set to an arbitrary value
for messages delivered to the mailbox using the APPEND command and is
usually copied from the source message for messages delivered using
the COPY command. In contrast, the save date attribute is always set
to the current date and time at the moment the message is saved in
the mailbox, irrespective of how the message is delivered and from
where it originates.
The save date attribute is useful for implementing automated removal
of messages from a mailbox after a configured amount of time. For
that application, it is necessary to know when the message was saved
in the mailbox, which cannot be reliably determined using the
internal date attribute.
For example, a common client usage pattern is to move deleted
messages to a Trash mailbox. These messages are considered "deleted"
at the time they are moved to the Trash mailbox. In an effort to
limit the size of the Trash mailbox, a client may subsequently desire
to permanently remove (expunge) all messages in that Trash mailbox
deleted before a certain time (e.g., a configurable expiration
interval). In that case, the internal date attribute cannot be used
since it likely refers to the time at which the message was
originally received. The proper time comparison attribute should
instead be the time at which the message was saved to the Trash
mailbox. Similar usage patterns can be observed for archiving
solutions.
The SAVEDATE capability extends the FETCH command and response to
allow retrieving the date and time at which a message was saved.
Also, the SAVEDATE capability extends the SEARCH command to allow
searching messages with criteria based on when they were saved in the
mailbox.
2. Conventions Used in This Document
In examples, "C:" indicates lines sent by a client that is connected
to a server. "S:" indicates lines sent by the server to the client.
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
"SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and
"OPTIONAL" in this document are to be interpreted as described in
BCP 14 [KEYWORDS] [KEYWORDS-UPD] when, and only when, they appear in
all capitals, as shown here.
3. Save Date Message Attribute
The save date message attribute is the date and time at which the
message was saved in the mailbox it is now located in. Unlike the
internal date message attribute defined by [IMAP4rev1], this date and
time value cannot be set arbitrarily when a message is delivered by
the IMAP APPEND command. Also, when a message is delivered to the
mailbox by the IMAP COPY command [IMAP4rev1] or the IMAP MOVE command
[IMAP-MOVE], the save date attribute is not copied from the source
message. Instead, the current date and time at which the message is
delivered to a mailbox MUST be used to set the save date attribute.
Once calculated, the save date attribute MUST NOT change as long as
the message is contained within the same mailbox.
This means that when the message is copied to another mailbox, the
save date of the message in the source mailbox remains unaffected;
only the new copy of the message gets a new save date. Consequently,
when the message is moved to another mailbox, either using the MOVE
command or a command sequence involving the COPY command [IMAP-MOVE],
the message always gets a new save date in the destination mailbox.
For some specific mailboxes, the underlying storage may not support
the save date attribute. The handling of this situation is described
in detail in the next section for each involved IMAP command.
4. IMAP Protocol Changes
4.1. CAPABILITY Identification
IMAP servers that support this extension MUST include "SAVEDATE" in
the response list to the CAPABILITY command.
4.2. FETCH Command and Response Extensions
This extension defines one new data item for the FETCH command:
SAVEDATE
The save date of the message.
This extension defines one new data item for the FETCH response:
SAVEDATE
A string representing the save date of the message. However, if
the underlying mailbox storage does not support the save date
message attribute, the value returned for the SAVEDATE item is
always NIL, rather than a string.
Example:
C: A101 FETCH 998 (SAVEDATE)
S: * 998 FETCH (SAVEDATE "01-Jan-2015 18:50:53 +0100")
S: A101 OK Fetch completed.
4.3. SEARCH Command Extension
This extension defines four new search keys for the SEARCH command:
SAVEDBEFORE <date>
Messages whose save date (disregarding time and timezone) is
earlier than the specified date.
SAVEDON <date>
Messages whose save date (disregarding time and timezone) is
within the specified date.
SAVEDSINCE <date>
Messages whose save date (disregarding time and timezone) is
within or later than the specified date.
SAVEDATESUPPORTED
Matches all messages in the mailbox when the underlying storage of
that mailbox supports the save date attribute. Conversely, it
matches no messages in the mailbox when the save date attribute is
not supported.
When the underlying storage of a mailbox does not support the save
date attribute, the SAVEDBEFORE, SAVEDON, and SAVEDSINCE search keys
MUST use the internal date attribute instead. In the context of the
IMAP Multimailbox SEARCH Extension [MULTISEARCH], this fallback
behavior MUST apply to each mailbox individually, meaning that only
the mailboxes that lack support for the save date attribute use the
internal date attribute instead.
Example:
C: A102 SEARCH SAVEDON 28-Dec-2014
S: * SEARCH 993 994
S: A102 OK Search completed.
C: A103 SEARCH SAVEDSINCE 28-Dec-2014
S: * SEARCH 993 994 995 996 997 998 999 1000 1001
S: A103 OK Search completed.
5. Formal Syntax
The following syntax specification augments the grammar specified in
[IMAP4rev1]. It uses the Augmented Backus-Naur Form (ABNF) notation
as specified in [ABNF]. Elements not defined here are taken from
[IMAP4rev1].
capability =/ "SAVEDATE"
fetch-att =/ "SAVEDATE"
msg-att-static =/ "SAVEDATE" SP (date-time / nil)
search-key =/ "SAVEDBEFORE" SP date /
"SAVEDON" SP date /
"SAVEDSINCE" SP date /
"SAVEDATESUPPORTED"
6. Security Considerations
There are no known additional security issues with this extension
beyond those described in the base protocol described in [IMAP4rev1].
7. IANA Considerations
IANA has added "SAVEDATE" to the "IMAP Capabilities" registry located
at <https://www.iana.org/assignments/imap-capabilities>.
8. Normative References
[ABNF] Crocker, D. and P. Overell, "Augmented BNF for Syntax
Specifications: ABNF", STD 68, RFC 5234,
DOI 10.17487/RFC5234, January 2008,
<https://www.rfc-editor.org/rfc/rfc5234>.
[IMAP-MOVE]
Gulbrandsen, A. and N. Freed, "Internet Message Access
Protocol (IMAP) - MOVE Extension", RFC 6851,
DOI 10.17487/RFC6851, January 2013,
<https://www.rfc-editor.org/rfc/rfc6851>.
[IMAP4rev1]
Crispin, M., "INTERNET MESSAGE ACCESS PROTOCOL - VERSION
4rev1", RFC 3501, DOI 10.17487/RFC3501, March 2003,
<https://www.rfc-editor.org/rfc/rfc3501>.
[KEYWORDS] Bradner, S., "Key words for use in RFCs to Indicate
Requirement Levels", BCP 14, RFC 2119,
DOI 10.17487/RFC2119, March 1997,
<https://www.rfc-editor.org/rfc/rfc2119>.
[KEYWORDS-UPD]
Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC
2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174,
May 2017, <https://www.rfc-editor.org/info/rfc8174>.
[MULTISEARCH]
Leiba, B. and A. Melnikov, "IMAP4 Multimailbox SEARCH
Extension", RFC 7377, DOI 10.17487/RFC7377, October 2014,
<https://www.rfc-editor.org/info/rfc7377>.
Acknowledgements
Thanks to Bron Gondwana, Alexey Melnikov, Timo Sirainen, and Michael
Slusarz for reviews and suggestions.
Author's Address
Stephan Bosch
Open Xchange Oy
Lars Sonckin kaari 12
Espoo 02600
Finland
Email: stephan.bosch@open-xchange.com
AI ELI5
On this page
§1Why a Save Date Is Needed
RFC 8514 extends the Internet Message Access Protocol (IMAP, RFC 3501) with a capability named SAVEDATE. It adds a message attribute called the save date: the date and time at which a message was saved in the mailbox where it currently lives.
IMAP already has an internal date. It is also set at delivery, but with APPEND it can be set to any value, and with COPY it is usually copied from the source message. The save date is always the current time at the moment of saving, no matter how the message arrived.
The motivating example is a Trash mailbox. A client that wants to permanently remove messages deleted more than a set time ago needs the time they were moved to Trash. The internal date likely points to when the message was first received, so it is the wrong clock. Archiving solutions have a similar need.
If you want to throw away things that have been in the junk drawer for a month, you need to know when each thing went into the drawer, not when you first bought it.
§2The Save Date Attribute
The server MUST set the save date to the current date and time whenever a message is delivered to a mailbox. It cannot be chosen by the client in an APPEND. It is not copied by COPY (RFC 3501) or MOVE (RFC 6851). Once set, it MUST NOT change while the message stays in the same mailbox.
The consequences follow directly. Copying a message leaves the original's save date alone, and only the new copy gets a fresh one. Moving a message always gives it a new save date in the destination mailbox.
Some mailboxes may be backed by storage that cannot keep a save date. The RFC describes how each command behaves in that case.
The date stamp is pressed on the moment a letter drops into a box. If you move the letter to another box, it gets a new stamp there.
§3FETCH and the Capability
A server that supports the extension MUST list SAVEDATE in its response to the CAPABILITY command.
The extension adds one FETCH data item, also called SAVEDATE. The response carries a string with the save date. If the underlying mailbox storage does not support the attribute, the value is always NIL instead of a string.
You can ask the mail server, "when did this letter land here?" If the box does not keep that note, the server answers "nothing."
- A101 FETCH 998 (SAVEDATE)
- * 998 FETCH (SAVEDATE "01-Jan-2015 18:50:53 +0100")
- A101 OK Fetch completed.
§4SEARCH Keys and Fallback
Four new SEARCH keys are defined. SAVEDBEFORE <date> matches messages saved earlier than the date. SAVEDON <date> matches messages saved on that date. SAVEDSINCE <date> matches messages saved on or after it. All three ignore time and timezone. SAVEDATESUPPORTED matches all messages in a mailbox when its storage supports the save date, and none when it does not.
When storage lacks the attribute, the three date keys MUST use the internal date instead. With the Multimailbox SEARCH extension (RFC 7377), this fallback MUST apply to each mailbox individually, so only the unsupporting mailboxes fall back.
You can ask for all letters that arrived before, on, or after a certain day. If a box does not keep arrival dates, the server uses the older date instead.
§5Formal Syntax
The grammar is given in ABNF (RFC 5234) as additions to the IMAP4rev1 grammar. It adds SAVEDATE as a capability and as a fetch attribute. A response item is SAVEDATE followed by a space and either a date-time or nil. The search keys take a date argument, except SAVEDATESUPPORTED, which takes none.
This is the exact spelling guide, so every mail program writes these new commands the same way.
§6Security and IANA Considerations
The RFC says there are no known additional security issues beyond those of the base IMAP protocol. For IANA, it adds SAVEDATE to the IMAP Capabilities registry.
Adding this date does not open any new doors for trouble, and the official list of IMAP features now includes it.