JMAP: a mail protocol written as a specification, not as a server

What JMAP replaces, and what it deliberately leaves alone

JMAP is a modern standard for email clients to connect to mail stores, and it therefore primarily replaces IMAP plus SMTP submission. The scope statement is careful on one point: it does not replace MTA-to-MTA SMTP transmission. Mail servers still talk to each other over SMTP, because that is a different problem, between different parties, on a different trust boundary. What JMAP replaces is the half of the protocol stack where a client talks to a store, which is where IMAP's design causes the most pain.

That distinction matters when you evaluate the standard. The problem with IMAP is not that it is old in a superficial sense. It is that it was designed for a world where a client was a separate program on a separate machine, connecting over a slow link to a server, and where the client was expected to hold state and manage the conversation. The result is a protocol with a large surface, a stateful session, and a lot of optional extension behaviour, all of which a modern web or mobile client has to negotiate on every connection.

JMAP, by contrast, is described as a modern standard and as a JSON Meta Application Protocol. The name tells you the two design decisions: the payload is JSON, and the protocol is a set of method calls over a small, uniform surface rather than a family of commands with different shapes.

The scope is also explicitly growing. The stated upcoming work includes adding contacts and calendars, replacing CardDAV and CalDAV, which is the natural next step because the same method-call model applies to those stores, and the repository already contains separate documents for them.

JMAP was built by the community and continues to improve through the IETF standardization process, with the working group linked from the repository. The pretty HTML version of the spec, along with more information and resources, is at jmap.io, which is also the homepage recorded for the project.

The repository is a document tree, and the Makefile is the build

The primary language recorded for this repository is Makefile, which tells you immediately that what is here is prose and the machinery that turns it into published documents rather than an implementation of anything.

The tree is organised by audience and stage. There is a `spec/` directory, which is the current working text. There is an `ietf-docs/` directory for the working group materials. There is an `rfc/` directory with a `src/` subdirectory of Markdown sources and a `build/` subdirectory for the generated output. There is a `client-guide/` and a `server-guide/`, which are the parts aimed at the two sides of the protocol. There is a `software/` directory, and a `home/` directory for the site.

The Makefile is the whole build system, and it is short enough to read in one pass. The interesting variable is the tool path, `MMARK:= ~/Code/mmark/mmark`, which is a hardcoded path to a local mmark binary. mmark is the Markdown processor used to turn the source into the XML that the RFC tooling consumes, and the fact that the path points into a specific developer's home directory means the build assumes you have mmark installed and either in that location or you have edited the variable.

The pattern rules are chained. A file in `rfc/build/` with a `.xml` suffix is built from the matching `.mdown` source in `rfc/src/`, and the rule depends on `spec/%/*` as well, which means a change anywhere in the spec directory triggers a rebuild of the RFC XML. The `.txt` and `.html` outputs are then produced from that XML by `xml2rfc`, once with the `--text` flag and once with the `--html` flag.

There is also a `clean` target that removes `rfc/build` entirely, and a `build` target that depends on a long list of specific outputs.

Seven documents, and one gap in the build list

The `build` target names the documents that get produced, and the list is the clearest available map of what the specification actually covers:

build: rfc/build/jmap.txt rfc/build/jmap.html rfc/build/mail.txt rfc/build/mail.html rfc/build/contacts.txt rfc/build/contacts.html rfc/build/calendars.txt rfc/build/calendars.html rfc/build/mdn.txt rfc/build/mdn.html rfc/build/tasks.txt rfc/build/tasks.html

Six documents, each in a text and an HTML form. `jmap` is the core protocol document. `mail` is the mail data model and operations on top of it. `contacts` and `calendars` are the two upcoming areas, replacing CardDAV and CalDAV. `mdn` is the message disposition notification specification, which is how a sender learns that a message was displayed, printed, or deleted. `tasks` is a task list document.

The `xml` target, which builds only the intermediate XML rather than the finished documents, names a slightly different set: `jmap.xml`, `mail.xml`, `contacts.xml`, `calendars.xml`, `mdn.xml`, `sharing.xml`, and `tasks.xml`.

The difference between the two lists is worth noting, because it is not noise. The XML target includes `sharing.xml` while the build target does not. So `sharing` is prepared but not published by the default build, and anyone working on sharing will find that the `build` target does not turn it into text or HTML. These are the kind of small inconsistencies that a two-rule Makefile accumulates, and anyone building the tree will hit them.

The `sharing` document is the one whose purpose is not obvious from the name alone, which is a hint that the shared document model is a distinct part of the design, separate from the store-specific models.

Every edit is a contribution to the IETF standards process

The contribution section of the project is unusual in its thoroughness, and it is the part a contributor has to understand before doing anything.

The repository relates to activities in the Internet Engineering Task Force. All material in the repository is considered Contributions to the IETF Standards Process, as defined in the intellectual property policies of IETF currently designated as BCP 78 and BCP 79, and the IETF Trust Legal Provisions relating to IETF Documents. Any edit, commit, pull request, issue, comment, or other change made in the repository constitutes Contributions to the IETF Standards Process. Contributors agree to comply with all applicable IETF policies and procedures, including BCP 78, BCP 79, the TLP, and the TLP rules regarding code components, which the text notes means being subject to a Simplified BSD License in Contributions.

Read that carefully, because it has a practical consequence. This is not a repository with an MIT or Apache licence that happens to contain a specification. The Apache-2.0 licence recorded for the repository and the IETF contribution terms are two different regimes, and the second one is about patent and copyright disclosure to the standards process rather than about permissions you as a user get. The code components clause is the part that catches contributors out, since a snippet of example code in an issue becomes a contribution with a specific licence attached.

The mailing list and the discussion preference are the other half of the process. JMAP is being developed within the IETF by the JMAP Working Group, and the mailing list at the IETF mailman is where the work happens. Feedback is welcome on anything that is imprecise, incomplete, or could simply be done better in another way, and the project states that discussion is preferred prior to pull requests, except in the case of minor typos and similar.

That last exception is a useful signal about how the text is maintained. A typo fix does not need a thread, but a wording change that alters what the standard requires does. For an implementer, that means a change in the spec text is not a routine pull request, it is a proposed modification to a standard that other implementations are coded against, and the discussion is where the argument happens.

The guides and the software directory are what implementers actually read

The `spec/` directory is the normative text, but the directories next to it are where an implementer spends most of their time.

There is a `client-guide/` and a `server-guide/`. The split is the right one for a protocol that has two sides, and it reflects the fact that the two sides have different problems. A client has to decide how to represent a mailbox, how to sync state, and how to handle a partial failure. A server has to decide how to store and index data, and how to answer a call that touches a lot of it. The core specification defines the method calls and the data models; the guides explain how to use them on each side.

The `software/` directory is the third piece, and its presence in a specification repository is a statement about the standard's maturity. A standard that ships with a list of implementations is a standard people are using, and a standard with no implementations is a document.

The `ietf-docs/` directory is separate from `spec/`, and the separation is meaningful in the IETF process. A document in the working group area is a draft that has not yet gone through the working group's own review, while the text in `spec/` is the current specification. The distinction between the two is the difference between a proposal and a document people code against.

The `home/` directory backs the site at jmap.io, which is described as the pretty HTML version of the spec along with more JMAP info and resources, so the website and the RFC build are two renderings of the same underlying text, generated from the same sources.

For a reader coming to JMAP for the first time, the practical path is the client guide for the shape of the protocol, the core spec for the exact method semantics, and the RFC build for the version that has actually been published.

Where this repository is the wrong place to look

The limits are obvious once you accept that this is a specification repository, but they are worth stating because the name suggests otherwise.

First, there is no implementation here. No client, no server, no SDK, no reference code. The `software/` directory is where implementations are listed, not where they live. If you are looking for a way to talk to a mail store over JMAP, this repository will not give you one, and the language recorded for the project, Makefile, is a hint that there is no library code to find.

Second, there is nothing to install and nothing to run. The build produces documents, and the artifacts are RFCs and their HTML and text renderings. There is no package on PyPI, no container image, and no command you can execute to get a working system.

Third, the build is not turnkey. The Makefile expects an mmark binary at a hardcoded path under a developer's home directory, and the RFC conversion needs `xml2rfc` on the path. Neither is installed by a dependency file, because there is no dependency file for the build. You will read the Makefile, install the two tools, adjust the path, and then you can produce the documents.

Fourth, the document set is a snapshot of a moving target. The protocol is being developed in a working group, and the spec text in the tree changes as the group revises it. The build list already contains `calendars`, which the surrounding text describes as upcoming work, and the `sharing` document is prepared but not published by the default build, which is exactly what you would expect from a standard with parts still in flight. Reading a version of the spec without checking where it sits in the process is how implementers end up coding against a draft.

Fifth, the contribution terms are not the usual open source terms. As set out in the previous section, any change you make here is a contribution to the IETF Standards Process, with the disclosure and licence consequences that implies. That is the correct arrangement for a standard, and it is not the arrangement you want if you were planning to use this repository as a convenient place to publish your own notes.

Finally, there are no GitHub releases. The last push was on 2026-10-14, so the tree moves, and the only stable artifacts are the published RFCs. A team that wants to reference a specific point of the specification has to reference the RFC, not a commit.

Editorial conclusion

This repository fits an engineer who needs to read what a mail client protocol actually says, who is implementing or reviewing a JMAP client or server, or who wants to follow the standard as it moves through the IETF working group. It is not a client library, a server implementation, or a tutorial, and it will not get you a working mail client. Check three things before you plan around it: that the document you need is in the tree, since the protocol is split across separate specs for mail, contacts, calendars, tasks, and shared documents, that you can build the RFCs yourself, which needs mmark and xml2rfc and the exact toolchain paths the Makefile expects, and that you read the IETF contribution terms before filing a pull request, because any change you make is a contribution to the standards process rather than an ordinary code contribution.

Frequently asked questions

Official sources

1. Issues
2. jmapio/jmap on GitHub
3. License: Apache-2.0
4. Project website
5. README