IMAP URL Scheme
obsoleted by
- rfc-5092 — IMAP URL Scheme
Extracted elements (25)
IMAP's modified UTF-7 encoding is private to IMAP and not easily interpreted by URL display programs, motivating the requirement to convert mailbox names to hex-encoded UTF-8 in URLs. Appendix A provides sample C code performing this conversion via the UTF-16 intermediate representation.
In IMAP URLs, parameters are treated as part of the normal path for relative URL resolution, deviating from RFC 1808. This is believed to match the behavior of the installed base and is expected to be documented in a future revision of the relative URL specification.
Relative IMAP mailbox paths only work correctly if the mailbox uses '/' as the hierarchy delimiter, since URLs always use '/' for path resolution. For mailboxes using other delimiters, the entire mailbox name MUST be specified in the relative URL or inherited as a whole from the base URL.
The `<iauth>` grammar element is considered part of the user name for relative URL resolution, meaning the authentication mechanism is inherited from the base IMAP URL unless explicitly overridden in the relative URL.
When resolving relative URLs for a message or message part, the program MUST check the MIME entity headers (Content-Base and Content-Location) of the referenced section and enclosing entities in order to determine the base URL, following the rules in RFC 2068 (HTTP/1.1).
A program interpreting IMAP URLs MAY cache open connections for re-use. If the URL contains a user name, only connections authenticated as that user may be re-used. If there is no user name or authentication mechanism, only an anonymous connection may be re-used.
Clear text passwords are not permitted in IMAP URLs. If the port is omitted, it defaults to 143.
Clients are discouraged from using plain text passwords as a fallback with `;AUTH=*` unless the connection has strong encryption (e.g., key length greater than 56 bits).
For mailbox list URLs, the field `;TYPE=<list_type>` MUST be included. The list type may be either 'LIST' or 'LSUB' and is case-insensitive. The program SHOULD use '%' as the list_mailbox wildcard if it supports a hierarchical view, otherwise SHOULD use '*'.
If no user name or authentication mechanism is supplied, the client MUST use the user name 'anonymous' with the LOGIN command and supply the end user's Internet e-mail address as the password. If the URL omits a user name, the program SHOULD request one from the user if necessary.
If the '/' character is present in `enc_list_mailbox` or `enc_mailbox`, it SHOULD NOT be encoded. Other unsafe or reserved characters such as space, semicolon, or '?' MUST be percent-encoded.
If unsafe or reserved characters such as space or semicolon are present in the user name or authentication mechanism, they MUST be percent-encoded as described in RFC 1738.
IMAP's modified UTF-7 encoding for mailbox names MUST be converted to UTF-8 before embedding in an IMAP URL. Since 8-bit characters are not permitted in URLs, the UTF-8 characters are then percent-encoded.
The string `;AUTH=*` indicates the client SHOULD select an appropriate authentication mechanism from the CAPABILITY list or use an out-of-band security service resulting in a PREAUTH connection. If no mechanism is available and no user name is given, the client SHOULD fall back to anonymous login.
When `;AUTH=<enc_auth_type>` is present, the client SHOULD request credentials from that mechanism and use the AUTHENTICATE command instead of LOGIN. If no user name is specified, one SHOULD be obtained from the mechanism or requested from the user.
A program interpreting a bare server URL (`imap://<iserver>/`) SHOULD use the LSUB form if it supports mailbox subscriptions, otherwise it may use LIST. This is semantically equivalent to `imap://<iserver>/;TYPE=LIST` or `imap://<iserver>/;TYPE=LSUB`.
The `[?<enc_search>]` field is optional in message list URLs. If present, it SHOULD be used as arguments to an IMAP4 SEARCH command. If absent, the program SHOULD present the full mailbox contents.
The IMAP URL scheme defines four forms: a server reference (`imap://<iserver>/`), a mailbox list (`imap://<iserver>/<enc_list_mailbox>;TYPE=<list_type>`), a message list or search result (`imap://<iserver>/<enc_mailbox>[uidvalidity][?<enc_search>]`), and a specific message or part (`imap://<iserver>/<enc_mailbox>[uidvalidity]<iuid>[isection]`).
The `<iuid>` field in a message part URL refers to an IMAP4 message UID and SHOULD be used as the set argument to the 'UID FETCH' command. The optional `[isection]` field maps to a MIME body section specifier used in 'UID FETCH <uid> BODY.PEEK[<section>]'.
The `[uidvalidity]` field in message list and message part URLs is optional. If present, it MUST be the value of the IMAP4 UIDVALIDITY status response at the time the URL was created, and SHOULD be used by the client to determine whether the URL is stale.
Email clients that store plain text passwords for IMAP MUST NOT use a stored password in response to an IMAP URL without explicit permission from the user to supply that password to the specified host name.
When resolving an IMAP URL that requires authentication, the program must verify the URL comes from a trusted source, local site policy permits the connection, the user confirms, a mechanism validates the server first, or the mechanism does not reveal information that could compromise future connections. URLs without a user name pose additional risk as they are more likely to compromise the user's primary account.
The `achar` terminal extends `uchar` (URL safe characters) with '&', '=', and '~'. The `bchar` terminal further adds ':', '@', and '/'. These define the character sets for encoded user names, auth types, mailbox names, and search programs.
The formal ABNF defines `imapurl = "imap://" iserver "/" [ icommand ]` where `icommand` is one of `imailboxlist`, `imessagelist`, or `imessagepart`. Key parameters use semicolon-prefixed names: `;TYPE=`, `;UID=`, `;SECTION=`, `;UIDVALIDITY=`, and `;AUTH=`.
The `iuserauth` component is `enc_user [iauth] / [enc_user] iauth`, where `iauth = ";AUTH=" ( "*" / enc_auth_type )`. The `uidvalidity` parameter is `";UIDVALIDITY=" nz_number` and `iuid` is `"/;UID=" nz_number`.