Internet Message Store Events
Extracted elements (30)
For scalability, some degree of filtering at event generation is necessary; at minimum, the ability to enable/disable groups of related events and suppress large parameters (such as messageContent) is required. A sophisticated publish/subscribe system may propagate cumulative subscription information upstream to the publisher.
Some event pairs (e.g., QuotaExceed/QuotaWithin) could be collapsed into a single event type with a distinguishing parameter, but until a subscription model is formulated it is impractical to make that decision, so they are defined as separate event types.
This document does not specify which event parameters are mandatory or optional for any given event; mandatory/optional status is determined by documents that define specific message formats or bindings to a notification system. Systems that cannot encode arbitrary (large or multi-line) parameter values can only implement a subset of these events.
For both FlagsSet and FlagsClear events, the flagNames parameter MUST NOT include \Recent. For FlagsSet, it SHOULD be configurable whether \Seen or \Deleted flag changes produce FlagsSet or the simpler MessageRead/MessageTrash events; the simpler forms SHOULD be the default.
For MessageExpunge, the parameters MUST include a mailbox identifier that includes UIDVALIDITY and a UID set describing the expunged messages.
For MessageNew, the message identifier parameters MUST include UIDVALIDITY and a UID for IMAP-accessible stores. The set of parameters SHOULD be adjustable to the client's preference, within limits set by server policy.
For QuotaExceed and QuotaWithin events, parameters SHOULD include at least the relevant user and quota, and optionally the mailbox. Quota usage SHOULD be included if possible.
Size-based suppression of the 'messageContent' parameter SHOULD be available so that implementations can avoid transmitting full message content with every notification.
When UIDVALIDITY changes, the client MUST flush its cache. UIDVALIDITY is critical to correct caching behavior and MUST be included with event notifications related to message addition or removal.
A message store event consists of a type and parameters. The type determines the event category; parameters supply context. Type and parameter names are restricted to US-ASCII printable characters, enabling mapping to arbitrary notification systems, though large or multi-line parameter values must be encodable.
FlagsClear event is generated when one or more IMAP flags or keywords are cleared on messages. Parameters include the cleared flag/keyword names, a mailbox identifier, and the UIDs of affected messages; \Recent MUST NOT appear in flagNames.
FlagsSet event is generated when one or more IMAP flags or keywords are set on messages. Parameters include the list of flag/keyword names set, a mailbox identifier, and the UIDs of affected messages.
Login event is generated when a user authenticates via IMAP, HTTP, POP, or another mechanism. Core parameters include server domain name, port, and authorization identity; optional parameters include client IP/port, authentication mechanism, negotiated security layer details, and timestamp.
Logout event is generated when a user disconnects from the message store. Parameters include server domain name and authorization identity; optional parameters MAY include disconnect type (graceful, abort, timeout, security layer error) and connection duration.
MailboxCreate event is generated when a mailbox is created or becomes accessible due to an ACL change. Parameters include the mailbox identifier and UIDVALIDITY for IMAP-accessible stores; implicit ancestor-mailbox creations do not generate separate events.
MailboxDelete event fires when a mailbox is deleted or becomes inaccessible via ACL change. Per IMAP4rev1 semantics the mailbox becomes \NOSELECT while child mailboxes and the hierarchy remain intact; only the named mailbox is affected.
MailboxRename event fires when a mailbox is renamed. Special IMAP semantics apply for INBOX (child mailboxes are excluded from the rename); implicit child renames and ancestor creations do not generate separate events. Parameters include old and new mailbox identifiers.
MailboxSubscribe and MailboxUnSubscribe events are generated when a mailbox is added to or removed from the server-stored subscription list (as managed by IMAP SUBSCRIBE/UNSUBSCRIBE). Parameters include the affected user, the mailbox identifier, and optionally the triggering access protocol.
MessageAppend event is generated when a message is appended or concatenated to a mailbox by a message access client. Unlike MessageNew, SMTP envelope information is not included, but the triggering protocol MAY be indicated.
MessageExpire event is generated when one or more messages are expired from a mailbox by server expiration policy. Parameters include a mailbox identifier that MUST include UIDVALIDITY and a UID set describing the expired messages.
MessageExpunge event is generated when one or more messages are expunged by IMAP CLOSE/EXPUNGE, POP3 DELE+QUIT, HTTP, or equivalent action. Parameters MUST include a mailbox identifier with UIDVALIDITY and a UID set, and MAY indicate the triggering access protocol.
MessageNew event is generated when a new message arrives via a message delivery agent. Parameters include a message identifier that MUST include UIDVALIDITY and a UID for IMAP-accessible stores, and MAY include SMTP envelope, message metadata, or the entire message content.
MessageRead and MessageTrash events signal that messages were marked as read/seen or flagged for future deletion, respectively. These are only generated by IMAP or HTTP clients (POP has no read/seen concept). Parameters include a mailbox identifier and a set of message UIDs.
QuotaExceed, QuotaWithin, and QuotaChange events cover quota lifecycle: QuotaExceed fires when an operation fails because a quota (disk, message count, etc.) was exceeded; QuotaWithin fires when usage drops below the limit; QuotaChange fires when the quota itself is modified.
The 'timestamp' parameter records the time of the triggering event (which may differ from notification generation time) in RFC 3339 format including UTC offset. The 'modseq' parameter carries the 64-bit MODSEQ integer (RFC 4551) for single-message notifications.
The 'uri' parameter is included with all notifications and provides a reference (typically an IMAP URL) to the server, mailbox, or message, optionally including server name, mailbox name, UIDVALIDITY, and message UID.
The 'user' parameter carries the authorization identity used by the client and is included with all events generated by message access protocols. The 'admin' parameter carries the authentication identity when it differs from the authorization identity.
IANA created a new 'Internet Message Store Events' registry with two sub-registries: event names and event parameters. Entries not starting with 'vnd.' are allocated by IETF Consensus for interoperable use; entries starting with 'vnd.' are allocated First Come First Served for private use.
A notification transfer protocol must address authentication, authorization, privacy, message integrity, and denial-of-service. Publish/subscribe protocols more complex than a single end-to-end TCP connection require extra attention to these issues and must carefully balance deployment requirements with security and privacy.
Notifications can expose sensitive information (e.g., message content, user activity) and produce high traffic volumes. An attacker able to modify notifications could corrupt state between entities, for example by falsifying audit log entries through altered 'user' and 'messageContent' parameters in MessageNew notifications.