Je winkelwagen is leeg
Producten die je toevoegt, verschijnen hier.
JMAP API in de praktijk: Session ophalen, back-references, synchroniseren met /changes, push en mail versturen. Met curl- en JSON-voorbeelden volgens de RFC.
Samenvatting: de JMAP API
Je haalt eerst de Session op met een GET op /.well-known/jmap en stuurt daarna al je method calls als één JSON-batch naar apiUrl. Met back-references ("#ids") koppel je Email/query en Email/get in één request. Met /changes haal je alleen op wat sinds een bekende state is veranderd, en push (EventSource, WebPush of WebSocket) vertelt je wanneer dat nodig is. Fouten komen op twee niveaus: een HTTP-fout met problem details voor het hele request, of een "error"-response per method call bij HTTP 200.
Dit is een praktische rondleiding door de JMAP API
KeurigOnline zegtAPIEen API (Application Programming Interface) is een set regels en protocollen waarmee softwareapplicaties met elkaar kunnen communiceren en gegevens uitwisselen.: RFC 8620 (core) en RFC 8621 (mail), met curl en JSON
KeurigOnline zegtJSONJSON (JavaScript Object Notation) is een tekstformaat waarmee websites, apps en API's gegevens uitwisselen., request én response. Wil je eerst weten wat JMAP is en waarom het IMAP
KeurigOnline zegtIMAPIMAP (Internet Message Access Protocol) is een protocol voor het ontvangen en beheren van e-mail op een externe server. kan vervangen, lees dan JMAP: wat is dat en wat lost het op.
In dat artikel filterde het voorbeeld op inMailbox: "inbox". Dat is fout: inMailbox neemt een Mailbox-id, geen rol[2]. Hieronder staat hoe het wel moet.
Alle voorbeelden gebruiken de host jmap.example.com, id's in de stijl van de RFC en een token in de variabele $JMAP_TOKEN. Responses zijn ingekort tot de velden die ertoe doen.

Een JMAP-client heeft twee dingen nodig: de URL van de Session-resource en credentials[1]. Die URL vind je via DNS
KeurigOnline zegtDNSHet Domain Name System (DNS) vertaalt domeinnamen naar IP-adressen, zodat websites makkelijk bereikbaar zijn. of via een vaste plek. Een host voor example.com zou (SHOULD) een SRV-record _jmap._tcp.example.com moeten publiceren met hostname en poort
KeurigOnline zegtPoortEen poort is een nummer van 0 tot 65535 waarmee een computer netwerkverkeer naar de juiste dienst stuurt, zoals 443 voor HTTPS., meestal 443. De Session staat dan op https://${hostname}[:${port}]/.well-known/jmap, waarbij je redirects volgt[1]. Hoe je zo'n record aanmaakt, staat in onze uitleg over geavanceerde DNS-configuratie met SRV-records.
# -L omdat de spec redirects toestaat
curl -sL -H "Authorization: Bearer $JMAP_TOKEN" \
https://jmap.example.com/.well-known/jmap
Een geauthenticeerde GET moet (MUST) een Session-object teruggeven[1]. Ingekort ziet dat er zo uit:
{
"capabilities": {
"urn:ietf:params:jmap:core": {
"maxSizeUpload": 50000000,
"maxSizeRequest": 10000000,
"maxCallsInRequest": 32,
"maxObjectsInGet": 256,
"maxObjectsInSet": 128
},
"urn:ietf:params:jmap:mail": {},
"urn:ietf:params:jmap:submission": {}
},
"accounts": {
"u1234": {
"name": "jan@example.com",
"isPersonal": true,
"isReadOnly": false,
"accountCapabilities": { "urn:ietf:params:jmap:mail": { "maxMailboxDepth": 10 } }
}
},
"primaryAccounts": { "urn:ietf:params:jmap:mail": "u1234" },
"username": "jan@example.com",
"apiUrl": "https://jmap.example.com/api/",
"downloadUrl": "https://jmap.example.com/download/{accountId}/{blobId}/{name}?accept={type}",
"uploadUrl": "https://jmap.example.com/upload/{accountId}/",
"eventSourceUrl": "https://jmap.example.com/eventsource/?types={types}&closeafter={closeafter}&ping={ping}",
"state": "75128aab4b1b"
}
Je account-id voor mail lees je uit primaryAccounts["urn:ietf:params:jmap:mail"], hier u1234. De limieten in urn:ietf:params:jmap:core bepalen hoe groot je batches mogen zijn: maxCallsInRequest per request, maxObjectsInGet per /get.
De drie URL's met accolades zijn URI Templates (RFC 6570, level 1). downloadUrl bevat de variabelen accountId, blobId, type en name, uploadUrl bevat accountId en eventSourceUrl bevat types, closeafter en ping[1]. Vul die templates in en bouw geen eigen paden: elke server kiest zijn eigen indeling.
Hoe je aan credentials komt, valt buiten RFC 8620[1]. Wel staat er dat Basic authentication NOT RECOMMENDED is; wie het toch gebruikt, hoort per client een apart app-wachtwoord te laten genereren[1]. In de praktijk gebruiken servers OAuth 2.0 of een Bearer-token[10]. Voor Basic vervang je de header door -u "$USER:$PASS".
Elk API-request is een POST naar apiUrl met een Request-object. Dat bevat using (de capabilities die je client wil gebruiken), methodCalls en optioneel createdIds[1]. Een method call is een array van drie elementen: de methodenaam, het argumentenobject en een method-call-id dat je zelf kiest[1]. De server verwerkt de method calls in de volgorde waarin ze staan (MUST)[1]. Daardoor kan een latere call het resultaat van een eerdere gebruiken.
curl -s -X POST https://jmap.example.com/api/ \
-H "Authorization: Bearer $JMAP_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"using": ["urn:ietf:params:jmap:core", "urn:ietf:params:jmap:mail"],
"methodCalls": [
["Mailbox/get", {
"accountId": "u1234",
"ids": null,
"properties": ["name", "role", "totalEmails"]
}, "c1"]
]
}'
Met "ids": null vraag je alle mailboxen van het account op. De response:
{
"methodResponses": [
["Mailbox/get", {
"accountId": "u1234",
"state": "78540",
"list": [
{ "id": "M7f6ed5bc", "name": "Inbox", "role": "inbox", "totalEmails": 1204 },
{ "id": "M2ea1ca41", "name": "Concepten", "role": "drafts", "totalEmails": 3 },
{ "id": "M3c9d0f17", "name": "Verzonden", "role": "sent", "totalEmails": 860 }
],
"notFound": []
}, "c1"]
],
"sessionState": "75128aab4b1b"
}
Elke response draagt het call-id van de call waar hij bij hoort, hier c1. Het id van een object komt altijd mee, ook als je het niet in properties zet[1]. De Response bevat verder methodResponses in verwerkingsvolgorde, createdIds alleen als je die meestuurde, en sessionState[1]. Wijkt sessionState af van de state in je bewaarde Session, dan is de Session veranderd en haal je hem opnieuw op.
Back-references maken batching nuttig. Je zet een # voor een argumentnaam en geeft als waarde een ResultReference met drie velden: resultOf (het call-id van een eerdere call in hetzelfde request), name (de verwachte responsenaam) en path[1]. Dat path is een JSON Pointer (RFC 6901) met één uitbreiding: * mapt over alle elementen van een array, en arrays van arrays worden platgeslagen tot één array.
Let op: back-references werken alleen op het hoogste niveau van de argumenten.
Elke mailbox heeft hoogstens één rol, en binnen een account hebben twee mailboxen nooit dezelfde rol (MUST NOT)[2]. Mailbox/query filtert op role[2]. Voor de id alleen is de query genoeg; de Mailbox/get erachter laat zien hoe een back-reference werkt.
"methodCalls": [
["Mailbox/query", { "accountId": "u1234", "filter": { "role": "inbox" } }, "a"],
["Mailbox/get", {
"accountId": "u1234",
"#ids": { "resultOf": "a", "name": "Mailbox/query", "path": "/ids" },
"properties": ["name", "role"]
}, "b"]
]
"methodResponses": [
["Mailbox/query", { "accountId": "u1234", "queryState": "m41",
"canCalculateChanges": true, "position": 0, "ids": ["M7f6ed5bc"] }, "a"],
["Mailbox/get", { "accountId": "u1234", "state": "78540",
"list": [{ "id": "M7f6ed5bc", "name": "Inbox", "role": "inbox" }],
"notFound": [] }, "b"]
]
Met de bewaarde id zet je Email/query en Email/get achter elkaar. De server lost /ids op uit de query-response en voert Email/get uit alsof je die id's zelf had meegegeven.
"methodCalls": [
["Email/query", {
"accountId": "u1234",
"filter": { "inMailbox": "M7f6ed5bc" },
"sort": [{ "property": "receivedAt", "isAscending": false }],
"limit": 10
}, "q"],
["Email/get", {
"accountId": "u1234",
"#ids": { "resultOf": "q", "name": "Email/query", "path": "/ids" },
"properties": ["id", "threadId", "subject", "from", "receivedAt", "preview"]
}, "g"]
]
"methodResponses": [
["Email/query", { "accountId": "u1234", "queryState": "q9c2",
"canCalculateChanges": true, "position": 0,
"ids": ["Ma1f0c3", "M88d2e1"] }, "q"],
["Email/get", { "accountId": "u1234", "state": "e5521", "list": [
{ "id": "Ma1f0c3", "threadId": "T41b7", "subject": "Offerte november",
"from": [{ "name": "Jan Jansen", "email": "jan@example.com" }],
"receivedAt": "2026-11-05T14:12:09Z", "preview": "Hoi, in de bijlage..." },
{ "id": "M88d2e1", "threadId": "T40aa", "subject": "Factuur oktober",
"from": [{ "name": "Boekhouding", "email": "factuur@example.org" }],
"receivedAt": "2026-11-04T09:30:00Z", "preview": "Bijgaand de factuur..." }
], "notFound": [] }, "g"]
]
Het RFC-voorbeeld gaat nog een stap verder: Thread/get met "path": "/list/*/threadId" haalt de threads van al die mails op, en een tweede Email/get met /list/*/emailIds alle mails in die threads[1]. Dat zijn vier calls en één round-trip.
Twee fouten horen hierbij. Lost een referentie niet op, dan weigert de server de hele call met invalidResultReference. Staan foo en #foo in dezelfde argumenten, dan krijg je invalidArguments[1].
Elke /get-response bevat een state. Bewaar die. Met Foo/changes vraag je daarna alleen op wat sinds die state is veranderd. Argumenten: accountId, sinceState en optioneel maxChanges. De response geeft oldState, newState, hasMoreChanges en drie id-lijsten: created, updated en destroyed[1].
Combineer dat met back-references en je hele sync is één request. Twee Email/get-calls verwijzen naar /created en /updated. Bij een Email kunnen na het aanmaken alleen mailboxIds en keywords veranderen; de headervelden zijn immutable[2]. Voor de bijgewerkte mails vraag je dus alleen die twee properties op.
"methodCalls": [
["Email/changes", { "accountId": "u1234", "sinceState": "e5521", "maxChanges": 200 }, "c"],
["Email/get", { "accountId": "u1234",
"#ids": { "resultOf": "c", "name": "Email/changes", "path": "/created" },
"properties": ["threadId", "mailboxIds", "keywords", "subject", "from", "receivedAt"] }, "n"],
["Email/get", { "accountId": "u1234",
"#ids": { "resultOf": "c", "name": "Email/changes", "path": "/updated" },
"properties": ["mailboxIds", "keywords"] }, "u"]
]
"methodResponses": [
["Email/changes", { "accountId": "u1234", "oldState": "e5521", "newState": "e5590",
"hasMoreChanges": false, "created": ["Mc30b11"], "updated": ["Ma1f0c3"],
"destroyed": ["M88d2e1"] }, "c"],
["Email/get", { "accountId": "u1234", "state": "e5590", "list": [{
"id": "Mc30b11", "threadId": "T42a1", "mailboxIds": { "M7f6ed5bc": true },
"keywords": {}, "subject": "Nieuwe bestelling",
"from": [{ "name": null, "email": "shop@example.net" }],
"receivedAt": "2026-11-06T08:02:11Z" }], "notFound": [] }, "n"],
["Email/get", { "accountId": "u1234", "state": "e5590", "list": [{
"id": "Ma1f0c3", "mailboxIds": { "M7f6ed5bc": true },
"keywords": { "$seen": true } }], "notFound": [] }, "u"]
]
Een sync-loop in 4 stappen
Email/changes met je bewaarde state als sinceState.Email/get-responses, de id's uit destroyed weg.hasMoreChanges true, roep dan opnieuw aan met newState als sinceState.newState op voor de volgende ronde.Krijg je cannotCalculateChanges, dan moet (MUST) je client zijn cache
KeurigOnline zegtCacheEen cache is een tijdelijke opslaglaag die veelgebruikte gegevens bewaart voor snellere toegang en betere prestaties. voor dat type weggooien en opnieuw opbouwen. Servers zouden (SHOULD) wijzigingen moeten kunnen berekenen vanaf elke state die in de afgelopen 30 dagen aan een client is gegeven[1]. Een client die langer offline was, moet dus rekening houden met een volledige resync.
Foo/query accepteert naast filter en sort ook position, anchor, anchorOffset, limit en calculateTotal. De response geeft queryState, canCalculateChanges, position en ids; total komt alleen mee als je erom vroeg[1].
Staat canCalculateChanges op true, dan kun je een lijst bijwerken met Foo/queryChanges. Je stuurt hetzelfde filter en sort mee, plus sinceQueryState en optioneel maxChanges en upToId. De response bevat oldQueryState, newQueryState, removed en added, waarbij elk toegevoegd item een id en een index heeft[1]:
["Email/queryChanges", { "accountId": "u1234",
"oldQueryState": "q9c2", "newQueryState": "q9d0",
"removed": ["M88d2e1"],
"added": [{ "id": "Mc30b11", "index": 0 }] }, "qc"]
Pas eerst de verwijderingen toe en voeg daarna de items in op hun index, van laag naar hoog. De server sorteert added op die manier (MUST)[1].
Alle wijzigingen lopen via Foo/set, met drie optionele argumenten: create (een map van creation-id naar nieuw object), update (een map van id naar PatchObject) en destroy (een lijst id's)[1]. De keys van een PatchObject zijn paden in het object, zonder de leading slash van een JSON Pointer. Met null verwijder je een waarde of zet je hem terug op de standaardwaarde.
Dit voorbeeld markeert een mail als gelezen en verplaatst hem van de inbox naar een archiefmap:
["Email/set", {
"accountId": "u1234",
"ifInState": "e5590",
"update": {
"Ma1f0c3": {
"keywords/$seen": true,
"mailboxIds/M7f6ed5bc": null,
"mailboxIds/M5d1a9e02": true
}
}
}, "s"]
["Email/set", {
"accountId": "u1234",
"oldState": "e5590", "newState": "e5604",
"created": null, "updated": { "Ma1f0c3": null }, "destroyed": null,
"notCreated": null, "notUpdated": null, "notDestroyed": null
}, "s"]
De response bevat oldState, newState, created, updated en destroyed, plus notCreated, notUpdated en notDestroyed met per id een SetError[1]. "Ma1f0c3": null in updated betekent: gelukt, en de server heeft niets anders aangepast dan wat je vroeg. Een mislukte update stopt de call niet. De server zet hem in notUpdated, bijvoorbeeld {"Mxyz": {"type": "notFound"}}, en gaat door met de volgende.
Met ifInState voer je de wijziging alleen uit als de huidige state gelijk is aan wat jij kent. Klopt dat niet, dan breekt de server de call af met stateMismatch[1]. Dan haal je eerst de wijzigingen op met /changes, controleer je of je wijziging nog klopt en probeer je het opnieuw. Wil je meer objecten tegelijk aanpassen dan de server toestaat, dan krijg je requestTooLarge; de limiet staat als maxObjectsInSet in de Session.
Een object dat je in hetzelfde request aanmaakt, heeft nog geen id. Je verwijst ernaar met zijn creation-id met een # ervoor. De call die het object aanmaakt, moet in hetzelfde request vóór de verwijzing staan of dezelfde call zijn[1]. Dat mechanisme gebruik je bij het versturen van mail, verderop.
Push in JMAP stuurt geen data mee. De server zegt alleen dat een state is veranderd, met een StateChange-object[1]:
{
"@type": "StateChange",
"changed": {
"u1234": { "Email": "e5604", "Mailbox": "78544" }
}
}
Vergelijk de state per type met wat je hebt. Wijkt hij af, dan haal je de data op met /changes uit de vorige sectie. Dat is het hele patroon. Het staat los van HTTP
KeurigOnline zegtHTTPHTTP (HyperText Transfer Protocol) is het protocol dat de communicatie tussen webclients en servers mogelijk maakt./2 Server Push, waarbij een webserver bestanden vooruit stuurt; dat leggen we uit in HTTP/2 Server Push en WordPress.
Een client die een verbinding open kan houden, doet een GET op de ingevulde eventSourceUrl en krijgt een text/event-stream[1]. De variabelen:
types: een kommalijst van typenamen, of * voor alles.closeafter: state sluit de response na één state-event, no houdt hem open. Gebruik state als een bufferende proxyping: interval in seconden voor een ping-event, 0 voor geen pings. Servers mogen het interval begrenzen, maar het minimum mag niet hoger zijn dan 30 en het maximum niet lager dan 300 (MUST NOT).curl -N -H "Authorization: Bearer $JMAP_TOKEN" -H "Accept: text/event-stream" \
"https://jmap.example.com/eventsource/?types=Email,Mailbox&closeafter=no&ping=60"
event: ping
data: {"interval":60}
event: state
id: 8a4d1f
data: {"@type":"StateChange","changed":{"u1234":{"Email":"e5604"}}}
De data van een ping is een object met interval, het interval dat de server echt gebruikt. Na een state-event zou (SHOULD) de server een nieuw event-id moeten sturen. Bij een nieuwe verbinding stuurt je client dat id als Last-Event-ID mee, en de server kan je dan de gemiste wijzigingen sturen[1].
Voor mobiele apps en browsers die niet constant verbonden zijn, registreer je een push-URL met PushSubscription/set[1]. Die call heeft geen accountId, omdat een push subscription niet bij één account hoort[1].
["PushSubscription/set", {
"create": {
"p1": {
"deviceClientId": "a889-ffea-910",
"url": "https://push.example.net/push/?device=X8980fc",
"keys": { "p256dh": "<base64url-publieke-sleutel>", "auth": "<base64url-auth-secret>" },
"types": ["Email", "Mailbox"]
}
}
}, "w"]
keys volgt RFC 8291 voor versleutelde push en is optioneel. De server stuurt eerst een PushVerification met pushSubscriptionId en verificationCode naar je URL. Pas als je die code met een update terugzet op de subscription, komen er StateChanges. Bij credentials zonder vervaltijd, zoals Basic, zou (SHOULD) de server zelf een expires moeten zetten. Dat maximum ligt minstens 48 uur in de toekomst (MUST) en bij voorkeur minstens 7 dagen (SHOULD)[1]. Lees expires dus terug en verleng de subscription op tijd.
Biedt de server in capabilities urn:ietf:params:jmap:websocket aan, met een url (wss) en supportsPush, dan kun je requests en push over één verbinding laten lopen[3]. De handshake gebruikt het subprotocol jmap. Een request krijgt "@type": "Request" en optioneel een id, omdat de server requests in een andere volgorde mag afhandelen; de Response draagt dat id terug als requestId[3].
{ "@type": "WebSocketPushEnable", "dataTypes": ["Mailbox", "Email"], "pushState": "aaa" }
{ "@type": "Request", "id": "R1",
"using": ["urn:ietf:params:jmap:core", "urn:ietf:params:jmap:mail"],
"methodCalls": [["Email/changes", { "accountId": "u1234", "sinceState": "e5604" }, "c"]] }
Met WebSocketPushEnable zet je push aan; dataTypes op null betekent alle types. StateChanges over de WebSocket
KeurigOnline zegtWebsocketEen websocket is een protocol voor een blijvende verbinding waarover browser en server tegelijk berichten sturen. kunnen een pushState bevatten. Stuur je de laatste bij een nieuwe verbinding mee, dan zou (SHOULD) de server je direct alle wijzigingen sinds dat moment moeten sturen. Uitzetten doe je met {"@type": "WebSocketPushDisable"}[3].
Versturen vereist de capability urn:ietf:params:jmap:submission, die de typen Identity en EmailSubmission toevoegt[2]. Zet hem in using naast core en mail.
Een Identity is een afzenderadres dat je mag gebruiken, met de velden id, name, email, replyTo, bcc, textSignature, htmlSignature en mayDelete[2].
["Identity/get", { "accountId": "u1234", "ids": null }, "i"]
["Identity/get", { "accountId": "u1234", "state": "id7", "list": [{
"id": "I64588216", "name": "Jan Jansen", "email": "jan@example.com",
"replyTo": null, "bcc": null, "textSignature": "", "htmlSignature": "",
"mayDelete": false }], "notFound": [] }, "i"]
De eerste call maakt het concept aan in de Drafts-mailbox (M2ea1ca41). De tweede maakt een EmailSubmission die met "#draft" naar dat concept verwijst. onSuccessUpdateEmail verplaatst de mail na verzending naar Verzonden (M3c9d0f17) en haalt $draft weg.
"methodCalls": [
["Email/set", { "accountId": "u1234", "create": { "draft": {
"mailboxIds": { "M2ea1ca41": true },
"keywords": { "$draft": true },
"from": [{ "name": "Jan Jansen", "email": "jan@example.com" }],
"to": [{ "email": "piet@example.org" }],
"subject": "Offerte november",
"bodyValues": { "b1": { "value": "Hoi Piet,\n\nDe offerte volgt morgen." } },
"textBody": [{ "partId": "b1", "type": "text/plain" }]
} } }, "e"],
["EmailSubmission/set", { "accountId": "u1234",
"create": { "k1": { "identityId": "I64588216", "emailId": "#draft" } },
"onSuccessUpdateEmail": { "#k1": {
"mailboxIds/M2ea1ca41": null,
"mailboxIds/M3c9d0f17": true,
"keywords/$draft": null } }
}, "s"]
]
"methodResponses": [
["Email/set", { "accountId": "u1234", "oldState": "e5604", "newState": "e5611",
"created": { "draft": { "id": "Md45e0a", "blobId": "G9b1f22",
"threadId": "T42c0", "size": 412 } } }, "e"],
["EmailSubmission/set", { "accountId": "u1234", "oldState": "s120", "newState": "s121",
"created": { "k1": { "id": "ES-3bab7f9a" } } }, "s"],
["Email/set", { "accountId": "u1234", "oldState": "e5611", "newState": "e5612",
"updated": { "Md45e0a": null } }, "s"]
]
De key #k1 in onSuccessUpdateEmail verwijst naar de creation-id van de EmailSubmission, niet naar de mail. Na alle creates voert de server één impliciete Email/set uit (MUST), en die response komt na de EmailSubmission-response met hetzelfde call-id s[2]. Daarom zie je twee responses voor s.
Een paar details uit de EmailSubmission-definitie[2]:
identityId geef je altijd expliciet mee, uit Identity/get.envelope met mailFrom en rcptTo is optioneel. Laat je hem weg, dan leidt de server hem af uit de Sender- of From-header en de ontvangers. Is dat adres niet toegestaan voor de Identity, dan gebruikt de server het email van de Identity.undoStatus is pending (annuleren kan misschien nog), final of canceled. Met deliveryStatus volg je de aflevering per ontvanger.Binaire data loopt buiten apiUrl om. Je uploadt met een geauthenticeerde POST naar de ingevulde uploadUrl; het Content-Type van je request wordt het type van de blob[1].
curl -s -X POST -H "Authorization: Bearer $JMAP_TOKEN" \
-H "Content-Type: application/pdf" --data-binary @offerte.pdf \
"https://jmap.example.com/upload/u1234/"
{"accountId":"u1234","blobId":"G4c5b0c7e","type":"application/pdf","size":48213}
De response bevat accountId, blobId, type en size. De data achter een blobId is immutable. Gebruik hem snel: in zeldzame gevallen heeft de server de blob al verwijderd voordat je hem gebruikt. Zolang er niets naar een blob verwijst, is hij alleen zichtbaar voor degene die hem uploadde[1]. Houd het lokale bestand dus bij de hand tot de mail is opgeslagen.
Als bijlage koppel je de blob in Email/set via attachments, naast textBody uit de vorige sectie:
"attachments": [{
"blobId": "G4c5b0c7e",
"type": "application/pdf",
"name": "offerte.pdf",
"disposition": "attachment"
}]
Downloaden doe je met een GET op de ingevulde downloadUrl, met de variabelen accountId, blobId, type en name[1]. In het Session-voorbeeld heet de variabele {type}, maar de query-parameter accept. Je vult dus de template in en bouwt het pad niet zelf. Level-1-expansie codeert gereserveerde tekens, waardoor de / in het mediatype %2F wordt:
curl -s -H "Authorization: Bearer $JMAP_TOKEN" -o offerte.pdf \
"https://jmap.example.com/download/u1234/G4c5b0c7e/offerte.pdf?accept=application%2Fpdf"
Omdat de inhoud nooit verandert, raadt de RFC servers lange cachetijden aan, bijvoorbeeld Cache-Control: private, immutable, max-age=31536000[1]. Een client kan downloads dus lokaal bewaren op blobId.
JMAP heeft twee foutniveaus, en een client die alleen naar de HTTP-status kijkt, mist de helft.
Kan de server het request als geheel niet verwerken, dan krijg je een HTTP-fout. De body zou (SHOULD) een problem-details-object volgens RFC 7807 moeten zijn[1]. Er zijn vier types:
urn:ietf:params:jmap:error:unknownCapability: iets in using kent de server niet.urn:ietf:params:jmap:error:notJSON: geen application/json, of geen geldige I-JSON.urn:ietf:params:jmap:error:notRequest: wel JSONurn:ietf:params:jmap:error:limit: een limiet uit de Session is overschreden. Het object moet (MUST) dan ook een limit-property met de naam van die limiet hebben.HTTP/1.1 400 Bad Request
Content-Type: application/problem+json
{
"type": "urn:ietf:params:jmap:error:limit",
"limit": "maxSizeRequest",
"status": 400,
"detail": "The request is larger than the server is willing to process."
}
Faalt een losse method call, dan zet de server een "error"-response op die plek in methodResponses. De volgende calls worden gewoon verwerkt, en een method-level fout mag (MUST NOT) geen HTTP-fout opleveren[1]. Behalve bij serverPartialFail is er na zo'n fout niets veranderd op de server.
HTTP/1.1 200 OK
{ "methodResponses": [
["Mailbox/get", { "accountId": "u1234", "state": "78540", "list": [], "notFound": [] }, "c1"],
["error", { "type": "unknownMethod" }, "c2"]
],
"sessionState": "75128aab4b1b" }
Algemene types zijn serverUnavailable, serverFail, serverPartialFail, unknownMethod, invalidArguments, invalidResultReference, forbidden, accountNotFound, accountNotSupportedByMethod en accountReadOnly. Een type dat je client niet kent, moet (MUST) hij behandelen als serverFail[1]. Per methode komen er types bij, zoals cannotCalculateChanges (/changes), stateMismatch en requestTooLarge (/set), anchorNotFound en unsupportedFilter (/query) en tooManyChanges (/queryChanges).
| Fout | Wat je client doet |
|---|---|
cannotCalculateChanges | Cache van dat type weggooien en volledig opnieuw ophalen (MUST) |
stateMismatch | Eerst /changes, wijziging controleren, dan opnieuw /set |
serverUnavailable | Later opnieuw proberen, met backoff en een willekeurige factor |
serverFail | Niet blind herhalen: hetzelfde request faalt naar verwachting opnieuw |
serverPartialFail | Betrokken data opnieuw synchroniseren (MUST) |
invalidArguments | Bug in je request; lees de description |
Controleer daarom elke methodResponse op de naam "error", ook als de HTTP-status 200 is.
Bovenop core en mail zijn extensies in eigen RFC's vastgelegd. Het IANA JMAP-register noemt onder meer deze capabilities (stand november 2026)[4].
urn:ietf:params:jmap:mdn[5].urn:ietf:params:jmap:quota, zonder quotabeheer[6].urn:ietf:params:jmap:contacts[7].urn:ietf:params:jmap:sieve[8].urn:ietf:params:jmap:principals[9].Tip: lees capabilities in de Session en zet in using alleen wat de server daar noemt. Een onbekende capability levert een request-level unknownCapability op.
Je hebt een server met een JMAP-endpoint nodig. Twee opties: een eigen Stalwart-server, die op jmap.io bij de JMAP-implementaties staat[12], of een Fastmail-account. De JMAP Crash Course laat een echte Fastmail-Session zien, met apiUrl https://api.fastmail.com/jmap/api/ en een Bearer-token[11].
Een gewone IMAP
KeurigOnline zegtIMAPIMAP (Internet Message Access Protocol) is een protocol voor het ontvangen en beheren van e-mail op een externe server.- of POP3
KeurigOnline zegtPOP3POP3 (Post Office Protocol versie 3) is een e-mailprotocol waarmee je berichten van een mailserver downloadt en lokaal opslaat.-mailbox heeft geen JMAP-endpoint. Twijfel je over je huidige mailserver, doe dan eerst de SRV-lookup en de GET op /.well-known/jmap uit de eerste sectie: zonder Session-object is er geen JMAP API
KeurigOnline zegtAPIEen API (Application Programming Interface) is een set regels en protocollen waarmee softwareapplicaties met elkaar kunnen communiceren en gegevens uitwisselen..
RFC 8620 schrijft geen methode voor: hoe je aan credentials komt, valt buiten de spec. Basic authentication is volgens RFC 8620 NOT RECOMMENDED, en wie het gebruikt, hoort per client een app-wachtwoord te laten genereren. In de praktijk gebruiken servers OAuth 2.0 of een Bearer-token in de Authorization-header.
inMailbox verwacht een Mailbox-id, geen rol (RFC 8621, sectie 4.4.1). Zoek de inbox eerst op met Mailbox/query en "filter": {"role": "inbox"}, bewaar de id die je terugkrijgt en gebruik die in je Email/query.
Niet volgens RFC 8620. De server zoekt #-argumenten alleen in het argumentenobject van de method call zelf (sectie 3.7), dus "#ids" werkt en "#inMailbox" binnen een filter niet. Haal de mailbox-id in een eerder request op en bewaar hem; id's zijn immutable.
Servers zouden (SHOULD) wijzigingen moeten kunnen berekenen vanaf elke state die in de afgelopen 30 dagen aan een client is gegeven. Lukt het niet, dan krijg je cannotCalculateChanges en moet (MUST) je client zijn cache
KeurigOnline zegtCacheEen cache is een tijdelijke opslaglaag die veelgebruikte gegevens bewaart voor snellere toegang en betere prestaties. voor dat type weggooien en opnieuw opbouwen (RFC 8620, sectie 5.2).
Nee. Een method-level fout staat als ["error", {"type": ...}, "call-id"] in methodResponses bij HTTP
KeurigOnline zegtHTTPHTTP (HyperText Transfer Protocol) is het protocol dat de communicatie tussen webclients en servers mogelijk maakt. 200, en de volgende calls worden gewoon uitgevoerd. Alleen een request dat als geheel ongeldig is, levert een HTTP-fout op met RFC 7807 problem details (RFC 8620, sectie 3.6).
EventSource (RFC 8620, sectie 7.3) is een gewone GET die alleen push levert en werkt op elke server met een eventSourceUrl. Buffert een proxy
KeurigOnline zegtProxyEen proxy is een tussenserver die verzoeken namens een ander doorstuurt en de antwoorden weer teruggeeft. de stream, gebruik dan closeafter=state. WebSocket
KeurigOnline zegtWebsocketEen websocket is een protocol voor een blijvende verbinding waarover browser en server tegelijk berichten sturen. (RFC 8887) combineert requests en push over één verbinding, maar alleen als de server urn:ietf:params:jmap:websocket aanbiedt.
/changes geeft de id's van objecten die zijn aangemaakt, gewijzigd of verwijderd sinds een state. /queryChanges werkt een zoekresultaat bij: welke id's uit de lijst zijn verdwenen (removed) en welke op welke positie zijn bijgekomen (added). Dat laatste kan alleen als de query-response canCalculateChanges: true had.