← RFC Reference

RFC 8620 : JMAP — Protocole d'application méta JSON

Pourquoi cela existe

IMAP fonctionne, mais il porte des décennies de complexité :

• Connexions TCP avec état. IMAP nécessite une connexion persistante par boîte aux lettres. Les clients mobiles sur des réseaux non fiables se reconnectent et se resynchronisent constamment.
• Protocole texte personnalisé. Le format de transmission IMAP nécessite des analyseurs spécialisés. Chaque langage a besoin d'une bibliothèque IMAP dédiée.
• Fragmentation des extensions. Les fonctionnalités critiques (CONDSTORE, MOVE, SPECIAL-USE) sont des extensions optionnelles que les serveurs peuvent ou non supporter.
• Limitations des notifications push. IMAP IDLE ne fonctionne que pour une boîte aux lettres à la fois, et de nombreux serveurs proxy/pare-feu interrompent les connexions TCP inactives.

JMAP résout tous ces problèmes. Il est sans état (chaque requête est autonome), utilise HTTPS (fonctionne à travers tous les serveurs proxy et pare-feu), utilise JSON (chaque langage a un analyseur), et définit les notifications push comme une fonctionnalité de première classe via EventSource ou Web Push.

Comment cela fonctionne

Découverte de service

Un client découvre le point de terminaison JMAP via un URI bien connu :

GET https://example.com/.well-known/jmap
{
  "capabilities": {
    "urn:ietf:params:jmap:core": { ... },
    "urn:ietf:params:jmap:mail": { ... }
  },
  "apiUrl": "https://jmap.example.com/api/",
  "uploadUrl": "https://jmap.example.com/upload/{accountId}/",
  "downloadUrl": "https://jmap.example.com/download/{accountId}/{blobId}/{name}",
  "eventSourceUrl": "https://jmap.example.com/events/"
}

Effectuer des appels API

Toutes les opérations JMAP sont envoyées en tant que POST unique à l'URL de l'API. Le corps de la requête contient un tableau d'appels de méthode, et la réponse contient les résultats correspondants :

POST https://jmap.example.com/api/
{
  "using": ["urn:ietf:params:jmap:core", "urn:ietf:params:jmap:mail"],
  "methodCalls": [
    ["Mailbox/get", { "accountId": "u1234", "ids": null }, "a"]
  ]
}

{
  "methodResponses": [
    ["Mailbox/get", {
      "accountId": "u1234",
      "state": "m42",
      "list": [
        { "id": "mb1", "name": "Inbox", "totalEmails": 142 },
        { "id": "mb2", "name": "Sent", "totalEmails": 87 },
        { "id": "mb3", "name": "Archive", "totalEmails": 4210 }
      ]
    }, "a"]
  ]
}

Traitement par lots et références arrière

Plusieurs appels de méthode peuvent être traités par lots dans une seule requête. Les références arrière permettent à un appel d'utiliser les résultats d'un appel précédent :

"methodCalls": [
  ["Email/query", {
    "accountId": "u1234",
    "filter": { "inMailbox": "mb1", "after": "2025-03-01T00:00:00Z" },
    "sort": [{ "property": "receivedAt", "isAscending": false }],
    "limit": 10
  }, "q"],
  ["Email/get", {
    "accountId": "u1234",
    "#ids": { "resultOf": "q", "name": "Email/query", "path": "/ids" },
    "properties": ["from", "subject", "receivedAt", "preview"]
  }, "g"]
]

Cela recherche la boîte de réception et récupère les 10 premiers résultats en un seul aller-retour HTTP — quelque chose qui nécessiterait plusieurs commandes IMAP.

Détails techniques clés

Chaînes d'état et synchronisation

Chaque réponse JMAP /get inclut une chaîne state. Pour synchroniser les modifications, le client appelle /changes avec le dernier état connu :

["Email/changes", { "accountId": "u1234", "sinceState": "e789" }, "c"]

["Email/changes", {
  "oldState": "e789",
  "newState": "e801",
  "created": ["em500", "em501"],
  "updated": ["em480"],
  "destroyed": ["em312"]
}, "c"]

Le client récupère ensuite uniquement les éléments créés/mis à jour. Ceci est plus efficace que CONDSTORE IMAP car il fonctionne sur toutes les boîtes aux lettres simultanément et ne nécessite pas une connexion persistante.

Notifications push

JMAP définit deux mécanismes push :

• EventSource : Le client ouvre une connexion SSE de longue durée à eventSourceUrl. Le serveur envoie des événements de changement d'état à mesure qu'ils se produisent.
• Web Push (RFC 8030) : Pour les clients mobiles/arrière-plan. Le serveur envoie des notifications push à une URL d'abonnement push fournie par le client.

Le modèle Foo/get, Foo/set, Foo/query

JMAP utilise un modèle de méthode uniforme pour chaque type de données :

Pour le courrier électronique, Foo est Email, Mailbox, Thread, EmailSubmission, etc. Cette cohérence signifie qu'une fois que vous comprenez un type de données, vous les comprenez tous.

Erreurs courantes

• Traiter JMAP comme une API REST traditionnelle. JMAP utilise un point de terminaison unique avec des appels de méthode dans le corps de la requête, pas des URL basées sur les ressources. N'essayez pas de le mapper aux conventions REST.
• Ignorer les chaînes d'état. Chaque réponse a un état. Si vous le rejetez, vous perdez la synchronisation efficace et devez tout re-récupérer à l'appel suivant.
• Récupérer toutes les propriétés. Email/get sans liste properties renvoie tout, y compris les corps complets des messages. Spécifiez toujours les propriétés dont vous avez besoin.
• Ne pas utiliser les références arrière. Faire des requêtes HTTP séparées pour requête + récupération gaspille un aller-retour. Utilisez les références arrière pour les traiter par lots.
• Supposer un support serveur universel. À partir de 2026, l'adoption JMAP est en croissance mais IMAP est toujours bien plus largement déployé. Fastmail est le fournisseur JMAP le plus en vue. Vérifiez les capacités du serveur avant de vous engager uniquement JMAP.
• Interroger au lieu d'utiliser push. JMAP fournit EventSource et Web Push précisément pour que vous n'ayez pas besoin d'interroger. Utilisez-les.

Impact sur la délivrabilité

• JMAP est principalement un protocole de récupération. Comme IMAP et POP3, il régit la façon dont les destinataires accèdent au courrier, et non la façon dont vous l'envoyez. Cependant, JMAP définit également EmailSubmission pour l'envoi, qui pourrait remplacer la soumission SMTP pour certains cas d'usage.
• Meilleures données d'engagement. L'approche structurée de JMAP concernant les indicateurs et les mouvements de boîtes aux lettres donne aux fournisseurs des signaux d'engagement plus nets. Lorsqu'un utilisateur déplace votre message de Courrier indésirable vers Boîte de réception via JMAP, le fournisseur voit un signal clair.
• Synchronisation client plus rapide. Parce que la synchronisation JMAP est plus efficace que IMAP, les clients mobiles restent synchronisés plus fiablement. Cela signifie que les destinataires voient vos messages plus rapidement et l'engagement (ouvertures, clics) se produit plus rapidement.
• Objet EmailSubmission. La méthode EmailSubmission/set de JMAP permet d'envoyer du courrier électronique via la même API utilisée pour la lecture. Pour les applications qui envoient et reçoivent, cela unifie l'ensemble du flux de travail de messagerie sous un seul protocole.

Related RFCs