IMAP JMAPACCESS: The JMAPACCESS Extension for IMAP
An IMAP extension that tells a logged-in client the same mail is also reachable through JMAP, and where.
Gulbrandsen, A. and B. Gondwana, "The JMAPACCESS Extension for IMAP", RFC 9698, DOI 10.17487/RFC9698, January 2025, <https://www.rfc-editor.org/info/rfc9698>.
@misc{rfc9698,
series = {Request for Comments},
number = 9698,
howpublished = {RFC 9698},
publisher = {RFC Editor},
doi = {10.17487/RFC9698},
url = {https://www.rfc-editor.org/info/rfc9698},
author = {A. Gulbrandsen and B. Gondwana},
title = {{The JMAPACCESS Extension for IMAP}},
pagetotal = 7,
year = 2025,
month = jan,
} RFC text
Contents
Internet Engineering Task Force (IETF) A. Gulbrandsen
Request for Comments: 9698 ICANN
Category: Standards Track B. Gondwana
ISSN: 2070-1721 Fastmail
January 2025
The JMAPACCESS Extension for IMAP
Abstract
This document defines an IMAP extension to let clients know that the
messages in this IMAP server are also available via the JSON Meta
Application Protocol (JMAP), and how. It is intended for clients
that want to migrate gradually to JMAP or use JMAP extensions within
an IMAP client.
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/rfc9698.
Copyright Notice
Copyright (c) 2025 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 Revised BSD License text as described in Section 4.e of the
Trust Legal Provisions and are provided without warranty as described
in the Revised BSD License.
Table of Contents
1. Introduction
2. Requirements Language
3. Details
4. The GETJMAPACCESS Command and the JMAPACCESS Response
5. Examples
6. IANA Considerations
7. Security Considerations
8. References
8.1. Normative References
8.2. Informative References
Authors' Addresses
1. Introduction
An IMAP server can declare that the messages in its mailstore are
also available via JMAP. For simplicity, only a complete equivalence
is supported (the same set of messages are available via both IMAP
and JMAP).
2. Requirements Language
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 [RFC2119] [RFC8174] when, and only when, they appear in all
capitals, as shown here.
3. Details
By advertising the JMAPACCESS capability, the server asserts that if
a mailbox or message has a particular object ID when accessed via
either IMAP or JMAP (see [RFC3501], [RFC9051], and [RFC8620]), then
the same mailbox or message is accessible via the other protocol, and
it has the same ID.
The server MUST also advertise the OBJECTID extension, defined by
[RFC8474]. The JMAP session resource that allows access to the same
messages is called "the JMAP server" below.
This specification does not affect message lifetime: If a client
accesses a message via IMAP and half a second later via JMAP, then
the message may have been deleted between the two accesses.
When the server processes the client's LOGIN/AUTHENTICATE command and
enters Authenticated state, the server considers the way the client
authenticated. If the IMAP server can infer from the client's
authentication process that its credentials suffice to authenticate
via JMAP, then the server MUST include a JMAPACCESS capability in any
capability list sent after that point. This includes the capability
list that some servers send immediately when authentication succeeds.
Servers are encouraged to report the same message flags and other
data via both protocols, as far as possible.
This specification does not require mailboxes to have the same name
in IMAP and JMAP, even if they share a mailbox ID. However, the JMAP
specification regulates that in the text about the name and role
properties described in Section 2 of [RFC8620].
Note that all JMAP servers support internationalized email addresses
(see [RFC6530]). If this IMAP server does not or if the IMAP client
does not issue ENABLE UTF8=ACCEPT (see [RFC6855]), then it is
possible that the client will receive accurate address fields via
JMAP and downgraded fields via IMAP (see [RFC6857] and [RFC6858] for
examples). Issuing ENABLE UTF8=ACCEPT is a simple way to sidestep
the issue.
4. The GETJMAPACCESS Command and the JMAPACCESS Response
The GETJMAPACCESS command requests that the server respond with the
session URL for the JMAP server that provides access to the same
mail.
If such a JMAP server is known to this server, the server MUST
respond with an untagged JMAPACCESS response containing the JMAP
server's session resource (a URL) followed by a tagged OK response.
If such a JMAP server is not known, the server MUST respond with a
tagged BAD response (and MUST NOT include JMAPACCESS in the
capability list).
The JMAPACCESS response is followed by a single link to a JMAP
session resource.
The formal syntax in [RFC9051] is extended as follows:
command-auth =/ "GETJMAPACCESS"
mailbox-data =/ resp-jmapaccess
resp-jmapaccess = "JMAPACCESS" SP quoted
The syntax in [RFC3501] is extended similarly (this extension may be
used with IMAP4rev1 as well as IMAP4rev2).
5. Examples
Lines sent by the client are preceded by C: and lines sent by the
server are preceded by S:. Each example starts with the IMAP banner
issued by the server on connection, and generally abbreviates the
capability lists to what's required by the example itself.
Real connections use longer capability lists, much longer
AUTHENTICATE arguments and of course use TLS. However, these
examples focus on JMAPACCESS.
Example 1:
A client connects, sees that SASL OAuth [RFC7628] is available, and
authenticates in that way.
S: * OK [CAPABILITY IMAP4rev1 AUTH=OAUTHBEARER SASL-IR] example1
C: 1 AUTHENTICATE OAUTHBEARER bixhPXVzZ...QEB
The server processes the command successfully. It knows that the
client used OAuth, and that it and its JMAP alter ego use the same
OAuth backend subsystem. Because of that it infers that the (next)
access token is just as usable via JMAP as via IMAP. It includes a
JMAPACCESS capability in its reply (again, real capability lists are
much longer):
S: 1 OK [CAPABILITY IMAP4rev1 JMAPACCESS] done
C: 1b GETJMAPACCESS
S: * JMAPACCESS "https://example.com/.well-known/jmap"
S: 1b OK done
SASL OAuth is specified by [RFC7628], and the argument in this
example is abbreviated from the more realistic length used in RFC
7628.
Example 2:
A client connects, sees no SASL method it recognizes, and issues a
LOGIN command.
S: * OK [CAPABILITY IMAP4rev2] example2
C: 2 LOGIN "arnt" "trondheim"
The server sees that the password is accepted, knows that it and its
JMAP alter ego use the same password database, and issues a
JMAPACCESS capability:
S: * OK [CAPABILITY IMAP4rev2 JMAPACCESS] done
S: 2 OK done
C: 2b JMAPACCESS
S: * JMAPACCESS "https://example.com/.well-known/jmap"
S: 2b OK done
The URL uses the same quoting rules as most other IMAP strings.
Example 3:
A client connects, sees no SASL method it recognizes, and issues a
LOGIN command with a correct password.
S: * OK [CAPABILITY IMAP4rev1 IMAP4rev2] example3
C: 3 LOGIN "arnt" "trondheim"
The server operator has decided to disable password use with JMAP,
but allow it for a while with IMAP to cater to older clients.
Therefore, the login succeeds, but there is no JMAPACCESS capability.
S: 3 OK done
Example 4:
A client connects, sees no SASL method it recognizes, and issues a
LOGIN command. Its password is incorrect.
S: * OK [CAPABILITY IMAP4rev2 AUTH=GSS] example4
C: 4 LOGIN "arnt" "oslo"
The server does not enter Authenticated state, so nothing requires it
to mention JMAPACCESS. It replies curtly:
S: 4 NO done
6. IANA Considerations
The IANA has added the JMAPACCESS capability to the "Internet Message
Access Protocol (IMAP) Capabilities Registry" and listed this
document as the reference.
7. Security Considerations
JMAPACCESS reveals to authenticated IMAP clients that they would be
able to authenticate via JMAP using the same credentials and that the
object IDs match.
One does not normally reveal anything at all about authentication.
However, if the client is an attacker, then the attacker is known to
have valid credentials, and Section 2.2 of [RFC8620] tells the
attacker how to find the revealed URL without the help of this
extension. Therefore, it is believed that this document does not
benefit an attacker noticeably, and its value for migration far
outweighs its risk.
8. References
8.1. Normative References
[RFC2119] 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/info/rfc2119>.
[RFC3501] Crispin, M., "INTERNET MESSAGE ACCESS PROTOCOL - VERSION
4rev1", RFC 3501, DOI 10.17487/RFC3501, March 2003,
<https://www.rfc-editor.org/info/rfc3501>.
[RFC8174] 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>.
[RFC8474] Gondwana, B., Ed., "IMAP Extension for Object
Identifiers", RFC 8474, DOI 10.17487/RFC8474, September
2018, <https://www.rfc-editor.org/info/rfc8474>.
[RFC9051] Melnikov, A., Ed. and B. Leiba, Ed., "Internet Message
Access Protocol (IMAP) - Version 4rev2", RFC 9051,
DOI 10.17487/RFC9051, August 2021,
<https://www.rfc-editor.org/info/rfc9051>.
8.2. Informative References
[RFC6530] Klensin, J. and Y. Ko, "Overview and Framework for
Internationalized Email", RFC 6530, DOI 10.17487/RFC6530,
February 2012, <https://www.rfc-editor.org/info/rfc6530>.
[RFC6855] Resnick, P., Ed., Newman, C., Ed., and S. Shen, Ed., "IMAP
Support for UTF-8", RFC 6855, DOI 10.17487/RFC6855, March
2013, <https://www.rfc-editor.org/info/rfc6855>.
[RFC6857] Fujiwara, K., "Post-Delivery Message Downgrading for
Internationalized Email Messages", RFC 6857,
DOI 10.17487/RFC6857, March 2013,
<https://www.rfc-editor.org/info/rfc6857>.
[RFC6858] Gulbrandsen, A., "Simplified POP and IMAP Downgrading for
Internationalized Email", RFC 6858, DOI 10.17487/RFC6858,
March 2013, <https://www.rfc-editor.org/info/rfc6858>.
[RFC7628] Mills, W., Showalter, T., and H. Tschofenig, "A Set of
Simple Authentication and Security Layer (SASL) Mechanisms
for OAuth", RFC 7628, DOI 10.17487/RFC7628, August 2015,
<https://www.rfc-editor.org/info/rfc7628>.
[RFC8620] Jenkins, N. and C. Newman, "The JSON Meta Application
Protocol (JMAP)", RFC 8620, DOI 10.17487/RFC8620, July
2019, <https://www.rfc-editor.org/info/rfc8620>.
Authors' Addresses
Arnt Gulbrandsen
ICANN
6 Rond Point Schumann, Bd. 1
1040 Brussels
Belgium
Email: arnt@gulbrandsen.priv.no
URI: https://icann.org/ua
Bron Gondwana
Fastmail
Level 2, 114 William St.
Melbourne VIC 3000
Australia
Email: brong@fastmailteam.com
URI: https://fastmail.com
AI ELI5
On this page
§1Why IMAP Needs to Point at JMAP
RFC 9698 defines an IMAP extension called JMAPACCESS. It lets an IMAP server declare that the messages in its mailstore are also available through JMAP, the JSON Meta Application Protocol defined in RFC 8620, and tells the client how to reach them.
The goal is gradual migration. A client can keep using IMAP while it starts using JMAP, or it can use JMAP extensions inside an IMAP client. For simplicity, only complete equivalence is supported: the same set of messages must be available through both protocols.
Some apps want to move from the old way of reading mail to a newer way, but not all at once. This sign tells them the newer way exists.
§3What the Capability Promises
By advertising the JMAPACCESS capability, the server asserts that if a mailbox or message has a particular object ID in IMAP or JMAP, then the same mailbox or message is accessible through the other protocol with the same ID. The server MUST also advertise the OBJECTID extension from RFC 8474. The JMAP session resource that reaches the same messages is called "the JMAP server" in the text.
Some things are deliberately not promised. Message lifetime is unaffected: a message read through IMAP may be gone half a second later when the client asks JMAP. Servers are encouraged, not required, to report the same flags and other data through both protocols. Mailboxes may have different names in IMAP and JMAP even when they share an ID.
The shared IDs are what make the two views line up: a client can find a message in one protocol and refer to it in the other.
Every folder and letter has the same name tag on both doors, so you can say which one you mean. But someone might throw a letter away between your two peeks.
§3.1When the Server Advertises It
The capability depends on how the client logged in. When the server processes LOGIN or AUTHENTICATE and enters Authenticated state, it considers the way the client authenticated. If it can infer that those credentials suffice to authenticate through JMAP, it MUST include JMAPACCESS in any capability list sent after that point, including the list some servers send immediately on success.
The examples in the RFC show the range. With SASL OAuth (RFC 7628), the server knows the OAuth backend is shared with its JMAP side, so the access token works for both. With LOGIN, the capability appears when IMAP and JMAP share a password database. If an operator has disabled passwords for JMAP but still allows them for IMAP, the login succeeds without the capability. If the password is wrong, the server never enters Authenticated state and need not mention JMAPACCESS at all.
The sign only shows up if your key also opens the new door. If your key only fits the old door, there is no sign.
§4The GETJMAPACCESS Command
The GETJMAPACCESS command asks the server for the session URL of the JMAP server that provides access to the same mail. It is added to the authenticated-state commands.
- If such a JMAP server is known, the server MUST send an untagged
JMAPACCESSresponse containing the session resource URL as a quoted string, followed by a taggedOK. - If none is known, the server MUST send a tagged
BADand MUST NOT includeJMAPACCESSin the capability list.
The formal syntax extends RFC 9051 with command-auth =/ "GETJMAPACCESS" and resp-jmapaccess = "JMAPACCESS" SP quoted. The syntax in RFC 3501 is extended similarly, so the extension works with IMAP4rev1 as well as IMAP4rev2.
You ask, "Where is the new door?" The server answers with the address, or says it does not know of one.
- AUTHENTICATE OAUTHBEARERClient logs in with SASL OAuth.
- OK [CAPABILITY ... JMAPACCESS]Server infers the credentials also work for JMAP.
- GETJMAPACCESS
- * JMAPACCESS "https://example.com/.well-known/jmap"Followed by a tagged OK.
§5Worked Examples
The RFC gives four examples. In the first, the client authenticates with AUTHENTICATE OAUTHBEARER; the server replies with a capability list containing JMAPACCESS, the client sends GETJMAPACCESS, and the server answers with the JMAP URL and OK. The second does the same after a successful LOGIN. The third shows a successful LOGIN with no capability because the operator disabled passwords for JMAP. The fourth shows a failed LOGIN, which just gets NO.
The RFC notes that real connections use longer capability lists, much longer AUTHENTICATE arguments and TLS; the examples are abbreviated to focus on JMAPACCESS.
The examples show a few ways of logging in. Sometimes the sign appears, sometimes it does not, and a wrong password gets a plain "no".
§3.2Internationalized Addresses
All JMAP servers support internationalized email addresses (RFC 6530). If the IMAP server does not, or if the IMAP client does not issue ENABLE UTF8=ACCEPT (RFC 6855), the client may receive accurate address fields through JMAP and downgraded fields through IMAP. The RFC points to RFC 6857 and RFC 6858 for examples of downgrading, and says that issuing ENABLE UTF8=ACCEPT is a simple way to sidestep the issue.
If the old door cannot show fancy letters in names, the new door may show them correctly. Asking the old door to allow fancy letters fixes the mismatch.
§7Security and IANA
JMAPACCESS reveals to authenticated IMAP clients that they could authenticate via JMAP with the same credentials, and that object IDs match. Normally nothing is revealed about authentication. The RFC argues this is acceptable: an attacker who sees it already has valid credentials, and Section 2.2 of RFC 8620 tells them how to find the URL without this extension. It concludes the extension does not noticeably help an attacker and that its migration value far outweighs the risk.
IANA added the JMAPACCESS capability to the IMAP Capabilities Registry.
The sign is only shown to people who already got in with a key, and they could have found the new door anyway, so little is given away.