JMAP

https://jmap.io/
Admin
JMAP is an open protocol that replaces IMAP (and CardDAV and CalDAV), offering a faster, simpler,...
Tokens:165,141
Snippets:1,765
Trust Score:9.7
Update:1 month ago
Show doc for...
Tokens:
Raw
### Directory Entry and Directory Service Examples

Source: https://jmap.io/spec/rfc9553

Examples demonstrating how to specify a directory entry for an individual and a directory service.

```json
"directories": {
  "dir1": {
    "kind": "entry",
    "uri": "https://dir.example.com/addrbook/jdoe/Jean%20Dupont.vcf"
  },
  "dir2": {
    "kind": "directory",
    "uri": "ldap://ldap.example/o=Example%20Tech,ou=Engineering",
    "pref": 1
  }
}
```

--------------------------------

### Simple Event Example

Source: https://jmap.io/spec/jscalendar-draft

Illustrates a simple one-time event with a start time and duration.

```json
{
  "@type": "Event",
  "version": "2.0",
  "uid": "a8df6573-0474-496d-8496-033ad45d7fea",
  "updated": "2020-01-02T18:23:04Z",
  "title": "Some event",
  "start": "2020-01-15T13:00:00",
  "timeZone": "America/New_York",
  "duration": "PT1H"
}
```

--------------------------------

### Sieve Script Get Response Example

Source: https://jmap.io/spec/rfc9661

This is an example response from a SieveScript/get request, showing the 'list' of scripts with their properties and 'notFound' array.

```jmap
[
  [
    "SieveScript/get",
    {
      "state": "1634915373.240633104-120",
      "list": [
        {
          "id": "2d647053-dded-418d-917a-63eda3ac8f7b",
          "name": "test1",
          "isActive": true,
          "blobId": "S7"
        }
      ],
      "notFound": [],
      "accountId": "ken"
    },
    "0"
  ]
]
```

--------------------------------

### Nickname Example

Source: https://jmap.io/spec/rfc9553

Example demonstrating the structure of the nicknames property within a Card object.

```json
{
  "nicknames": {
    "k391": {
      "name": "Johnny"
    }
  }

}
```

--------------------------------

### Name Component Example

Source: https://jmap.io/spec/rfc9553

Example demonstrating the structure of a Name component with multiple given and surname parts, and the sortAs property.

```json
{
  "name": {
    "components": [
      { "kind": "given", "value": "Robert" },
      { "kind": "given2", "value": "Pau" },
      { "kind": "surname", "value": "Shou Chang" }
    ],
    "sortAs": {
      "surname": "Pau Shou Chang",
      "given": "Robert"
    },
    "isOrdered": true
  }

}
```

--------------------------------

### Email/get Response Example

Source: https://jmap.io/spec/rfc8621

An example response to an Email/get request, showing fetched email properties, headers, and body part details.

```json
[[ "Email/get", {
  "accountId": "abc",
  "state": "41234123231",
  "list": [
    {
      "id": "f123u457",
      "threadId": "ef1314a",
      "mailboxIds": { "f123": true },
      "from": [{ "name": "Joe Bloggs", "email": "joe@example.com" }],
      "subject": "Dinner on Thursday?",
      "receivedAt": "2013-10-13T14:12:00Z",
      "header:List-POST:asURLs": [
        "mailto:partytime@lists.example.com"
      ],
      "htmlBody": [{
        "partId": "1",
        "blobId": "B841623871",
        "size": 283331,
        "type": "text/html"
      }, {
        "partId": "2",
        "blobId": "B319437193",
        "size": 10343,
        "type": "text/plain"
      }],
      "bodyValues": {
        "1": {
          "isEncodingProblem": false,
          "isTruncated": true,
          "value": "<html><body><p>Hello ..."
        },
        "2": {
          "isEncodingProblem": false,
          "isTruncated": false,
          "value": "-- Sent by your friendly mailing list ..."
        }
      }
    }
  ],
  "notFound": [ "f123u456" ]
}, "#1" ]]
```

--------------------------------

### JMAP Method Responses Example

Source: https://jmap.io/spec/rfc8620

Example of method responses after executing the first 3 calls in a JMAP sequence.

```json
[[ "Email/query", {
    "accountId": "A1",
    "queryState": "abcdefg",
    "canCalculateChanges": true,
    "position": 0,
    "total": 101,
    "ids": [ "msg1023", "msg223", "msg110", "msg93", "msg91",
        "msg38", "msg36", "msg33", "msg11", "msg1" ]
}, "t0" ],
[ "Email/get", {
    "accountId": "A1",
    "state": "123456",
    "list": [{
        "id": "msg1023",
        "threadId": "trd194"
    }, {
        "id": "msg223",
        "threadId": "trd114"
    },
    ...
    ],
    "notFound": []
}, "t1" ],
[ "Thread/get", {
    "accountId": "A1",
    "state": "123456",
    "list": [{
        "id": "trd194",
        "emailIds": [ "msg1020", "msg1021", "msg1023" ]
    }, {
        "id": "trd114",
        "emailIds": [ "msg201", "msg223" ]
    },
    ...
    ],
    "notFound": []
}, "t2" ]]

```

--------------------------------

### Email/get Request Example

Source: https://jmap.io/spec/rfc8621

An example of an Email/get request specifying various properties to fetch, including custom headers and body content options.

```json
[[ "Email/get", {
  "ids": [ "f123u456", "f123u457" ],
  "properties": [ "threadId", "mailboxIds", "from", "subject",
    "receivedAt", "header:List-POST:asURLs",
    "htmlBody", "bodyValues" ],
  "bodyProperties": [ "partId", "blobId", "size", "type" ],
  "fetchHTMLBodyValues": true,
  "maxBodyValueBytes": 256
}, "#1" ]]
```

--------------------------------

### HTTP Accept-Language Header Example

Source: https://jmap.io/spec/rfc8620

Example Accept-Language header indicating user's preferred languages for localization.

```http
Accept-Language: fr-CH, fr;q=0.9, de;q=0.8, en;q=0.7, *;q=0.5

```

--------------------------------

### JMAP Principal/get Response Example

Source: https://jmap.io/spec/rfc9670

Provides an example of a JMAP response for a Principal/get request, listing principals and their capabilities, including sharing permissions.

```json
[[ "Principal/get", {
  "accountId": "u33084183",
  "state": "7b8eff5zz",
  "list": [{
    "id": "P2342fnddd20",
    "type": "individual",
    "name": "Joe Bloggs",
    "description": null,
    "email": "joe.bloggs@example.com",
    "timeZone": "Australia/Melbourne",
    "capabilities": {
        "urn:com.example:jmap:todo": {
            "accountId": null,
            "mayShareWith": true
        }
    },
    "accounts": null
  }, {
    "id": "P674pp24095qo49pr",
    "name": "Board room",
    "type": "location",
    ...
  }, ... ],
  "notFound": []
}, "0" ]]
```

--------------------------------

### Simple Task Example

Source: https://jmap.io/spec/jscalendar-draft

Illustrates a simple task for a plain to-do item.

```json
{
  "@type": "Task",
  "version": "2.0",
  "uid": "2a358cee-6489-4f14-a57f-c104db4dc2f2",
  "updated": "2020-01-09T14:32:01Z",
  "title": "Do something"
}
```

--------------------------------

### JMAP Foo/get Arguments

Source: https://jmap.io/spec/rfc8620

Example arguments for a JMAP Foo/get call.

```json
{
    "accountId": "A1",
    "ids": [ "f1", "f4" ]
}

```

--------------------------------

### Combined Get Response for SieveScript and Blob

Source: https://jmap.io/spec/rfc9661

This example shows the combined response from fetching Sieve script properties and content using SieveScript/get and Blob/get. The Blob/get response includes the script data as 'data:asText'.

```jmap
[
  [
    "SieveScript/get",
    {
      "state": "1634915373.240633104-120",
      "list": [
        {
          "id": "2d647053-dded-418d-917a-63eda3ac8f7b",
          "name": "test1",
          "isActive": true,
          "blobId": "S7"
        }
      ],
      "notFound": [],
      "accountId": "ken"
    },
    "0"
  ],
  [
    "Blob/get",
    {
      "list": [
        {
          "id": "S7",
          "data:asText":
     "require [\"fileinto\"];\r\nfileinto \"INBOX.target\";\r\n",
          "size": 49
        }
      ],
      "notFound": [],
      "accountId": "ken"
    },
    "1"
  ]
]
```

--------------------------------

### JMAP Blob/get Example (Method Calls)

Source: https://jmap.io/spec/rfc9404

Shows how to retrieve specific properties of a blob using Blob/get. Useful for fetching blob metadata or content ranges.

```json
[["Blob/get",{"properties":["data:asText","size"],"ids":["#cat"]}],"G4"]
```

--------------------------------

### JMAP Cold Boot Response Example

Source: https://jmap.io/client/index.html

This is a sample JMAP response simulating a cold boot. It includes results from Email/query, Email/get, and Thread/get methods to populate an initial email interface view.

```json
[
    [ "Email/query", {
        "accountId": "u123456",
        "ids": [
            "fm1u314",
            "fm1u312",
            "fm1u298",
            "fm1u286",
            "fm1u265",
            "fm1u254",
            "fm1u241",
            "fm1u211",
            "fm1u109",
            "fm1u313"
        ],
        "queryState": "123:0",
        "position": 0,
        "canCalculateChanges": true,
        "total": 10
    }, "0" ],
    [ "Email/get", {
        "accountId": "u123456",
        "list": [
            { "id": "fm1u314", "threadId": "4f512aafed75e7fb" },
            { "id": "fm1u312", "threadId": "fed75e7fb4f512aa" },
            { "id": "fm1u298", "threadId": "75e7fb4f512aafed" },
            { "id": "fm1u286", "threadId": "512aafed75e7fb4f" },
            { "id": "fm1u265", "threadId": "fb4f512aafed75e7" },
            { "id": "fm1u254", "threadId": "2aafed75e7fb4f51" },
            { "id": "fm1u241", "threadId": "afed75fb4f512ae7" },
            { "id": "fm1u211", "threadId": "e7fb4f512aafed75" },
            { "id": "fm1u109", "threadId": "ed75e74f51fb2aaf" },
            { "id": "fm1u313", "threadId": "b4f5ed75e712aaff" }
        ],
        "state": "123",
        "notFound": []
    }, "1" ],
    [ "Thread/get", {
        "accountId": "u123456",
        "list": [
            { "id": "4f512aafed75e7fb", "emailIds": [ ... ] },
            { "id": "fed75e7fb4f512aa", "emailIds": [ ... ] },
            { "id": "75e7fb4f512aafed", "emailIds": [ ... ] },
            { "id": "512aafed75e7fb4f", "emailIds": [ ... ] },
            { "id": "fb4f512aafed75e7", "emailIds": [ ... ] },
            { "id": "2aafed75e7fb4f51", "emailIds": [ ... ] },
            { "id": "afed75fb4f512ae7", "emailIds": [ ... ] },
            { "id": "e7fb4f512aafed75", "emailIds": [ ... ] },
            { "id": "ed75e74f51fb2aaf", "emailIds": [ ... ] },
            { "id": "b4f5ed75e712aaff", "emailIds": [ ... ] }
        ],
        "state": "123"
    }, "2" ],
    [ "Email/get", {
        "accountId": "u123456",
        "list": [{
            "id": "fm1u314",
            "threadId": "4f512aafed75e7fb",
            "mailboxIds": {
                "mailbox1": true
            },
            "keywords": {
                "$seen": true
            },
            "hasAttachment": false,
            "from": [
                { "name": "Joe Bloggs", "email": "joebloggs@example.com" }
            ],
            "to": [
                { "name": "Jane Doe", "email": "janedoe@example.com" }
            ],
            "subject": "Camping trip",
            "receivedAt": "2014-07-24T15:04:51Z",
            "preview": "Hey Joe. Fancy a trip out west next week? I hea…"
        }, ... ],
        "state": "123",
        "notFound": []
    }, "3" ]
]

```

--------------------------------

### HTTP Content-Language Header Example

Source: https://jmap.io/spec/rfc8620

Example Content-Language header indicating the language used for user-visible strings in the response.

```http
Content-Language: de

```

--------------------------------

### JMAP Todo/query and Todo/get Example

Source: https://jmap.io/spec/rfc8620

Demonstrates a JMAP client request to query for Todos with specific keywords and then fetch the full objects using back-references.

```json
[[ "Todo/query", {
  "accountId": "x",
  "filter": {
    "operator": "OR",
    "conditions": [
      { "hasKeyword": "music" },
      { "hasKeyword": "video" }
    ]
  },
  "sort": [{ "property": "title" }],
  "position": 0,
  "limit": 10
}, "0" ],
[ "Todo/get", {
  "accountId": "x",
  "#ids": {
    "resultOf": "0",
    "name": "Todo/query",
    "path": "/ids"
  }
}, "1" ]]
```

```json
[[ "Todo/query", {
  "accountId": "x",
  "queryState": "y13213",
  "canCalculateChanges": true,
  "position": 0,
  "ids": [ "a", "b", "c", "d", "e", "f", "g", "h", "i", "j" ]
}, "0" ],
[ "Todo/get", {
  "accountId": "x",
  "state": "10324",
  "list": [{
    "id": "a",
    "title": "Practise Piano",
    "keywords": {
      "music": true,
      "beethoven": true,
      "mozart": true,
      "liszt": true,
      "rachmaninov": true
    },
    "neuralNetworkTimeEstimation": 3600
  }, {
    "id": "b",
    "title": "Watch Daft Punk music video",
    "keywords": {
      "music": true,
      "video": true,
      "trance": true
    },
    "neuralNetworkTimeEstimation": 18000
  },
  ...
  ]
}, "1" ]]
```

--------------------------------

### JSContact Card relatedTo Property Example

Source: https://jmap.io/spec/rfc9553

Example of the 'relatedTo' property for a JSContact Card, showing relationships with other cards.

```json
"relatedTo": {
  "urn:uuid:f81d4fae-7dec-11d0-a765-00a0c91e6bf6": {
    "relation": {
      "friend": true
    }
  },
  "8cacdfb7d1ffdb59@example.com": {
    "relation": {}
  }
}
```

--------------------------------

### JSContact Card version Property Example

Source: https://jmap.io/spec/rfc9553

Example of the 'version' property for a JSContact Card, indicating the JSContact version.

```json
"version": "1.0"
```

--------------------------------

### Example Mailbox Response

Source: https://jmap.io/client

This is an example response from a Mailbox/get request, detailing mailbox properties, counts, and user permissions.

```json
[
    [
        "Mailbox/get",
        {
            "accountId": "u123456",
            "state": "123",
            "list": [
                {
                    "id": "mailbox1",
                    "name": "Inbox",
                    "parentId": null,
                    "role": "inbox",
                    "sortOrder": 0,
                    "totalEmails": 1424,
                    "unreadEmails": 3,
                    "totalThreads": 1213,
                    "unreadThreads": 2,
                    "myRights": {
                        "mayAddItems": true,
                        "mayRename": false,
                        "maySubmit": true,
                        "mayDelete": false,
                        "maySetKeywords": true,
                        "mayRemoveItems": true,
                        "mayCreateChild": true,
                        "maySetSeen": true,
                        "mayReadItems": true
                    },
                    "isSubscribed": true
                },
                {
                    "id": "mailbox2",
                    "name": "Sent",
                    "parentId": null,
                    "role": "sent",
                    "sortOrder": 0,
                    "totalEmails": 41,
                    "unreadEmails": 0,
                    "totalThreads": 32,
                    "unreadThreads": 2,
                    "myRights": {
                        "mayAddItems": true,
                        "mayRename": false,
                        "maySubmit": true,
                        "mayDelete": false,
                        "maySetKeywords": true,
                        "mayRemoveItems": true,
                        "mayCreateChild": true,
                        "maySetSeen": true,
                        "mayReadItems": true
                    },
                    "isSubscribed": true
                },
                {
                    "id": "mailbox3",
                    "name": "Trash",
                    "parentId": null,
                    "role": "trash",
                    "sortOrder": 0,
                    "totalEmails": 3,
                    "unreadEmails": 0,
                    "totalThreads": 2,
                    "unreadThreads": 0,
                    "myRights": {
                        "mayAddItems": true,
                        "mayRename": false,
                        "maySubmit": true,
                        "mayDelete": false,
                        "maySetKeywords": true,
                        "mayRemoveItems": true,
                        "mayCreateChild": false,
                        "maySetSeen": true,
                        "mayReadItems": true
                    },
                    "isSubscribed": true
                },
                {
                    "id": "mailbox4",
                    "name": "Awaiting Reply",
                    "parentId": "mailbox2",
                    "role": null,
                    "sortOrder": 0,
                    "totalEmails": 0,
                    "unreadEmails": 0,
                    "totalThreads": 0,
                    "unreadThreads": 0,
                    "myRights": {
                        "mayAddItems": true,
                        "mayRename": false,
                        "maySubmit": true,
                        "mayDelete": false,
                        "maySetKeywords": true,
                        "mayRemoveItems": true,
                        "mayCreateChild": true,
                        "maySetSeen": true,
                        "mayReadItems": true
                    },
                    "isSubscribed": true
                }
            ],
            "notFound": []
        },
        "0"
    ]
]
```

--------------------------------

### JMAP Blob/upload Complex Example (Method Calls)

Source: https://jmap.io/spec/rfc9404

Demonstrates a complex sequence of Blob/upload calls to create and reference blobs. Use this for advanced blob manipulation scenarios.

```json
[["Blob/upload",{"create":{"b4":{"data":[{"data:asText":"The quick brown fox jumped over the lazy dog."}]}}}] ,"S4"]
```

```json
[["Blob/upload",{"create":{"cat":{"data":[{"data:asText":"How"},{"blobId":"#b4","length":7,"offset":3},{"data:asText":"was t"},{"blobId":"#b4","length":1,"offset":1},{"data:asBase64":"YXQ/"}]}}}] ,"CAT"]
```

--------------------------------

### JSContact Card uid Property Example

Source: https://jmap.io/spec/rfc9553

Example of the 'uid' property for a JSContact Card, providing a unique identifier for the card.

```json
"uid": "urn:uuid:f81d4fae-7dec-11d0-a765-00a0c91e6bf6"
```

--------------------------------

### JSContact Card prodId Property Example

Source: https://jmap.io/spec/rfc9553

Example of the 'prodId' property for a JSContact Card, identifying the product that created the card.

```json
"prodId": "ACME Contacts App version 1.23.5"
```

--------------------------------

### Example Email Sort Configuration

Source: https://jmap.io/spec/rfc8621

Demonstrates a multi-property sort configuration for emails, prioritizing flagged threads, then subject, then received date.

```json
[
  {
    "property": "someInThreadHaveKeyword",
    "keyword": "$flagged",
    "isAscending": false
  }, {
    "property": "subject",
    "collation": "i;ascii-casemap"
  }, {
    "property": "receivedAt",
    "isAscending": false
  }
]
```

--------------------------------

### Example Calendars Property

Source: https://jmap.io/spec/rfc9553

Illustrates the structure for defining calendaring resources, including types like 'calendar' and 'freeBusy' with their respective URIs.

```json
"calendars": {
  "calA": {
    "kind": "calendar",
    "uri": "webcal://calendar.example.com/calA.ics"
  },
  "project-a": {
    "kind": "freeBusy",
    "uri": "https://calendar.example.com/busy/project-a"
  }
}
```

--------------------------------

### JSContact Card kind Property Example

Source: https://jmap.io/spec/rfc9553

Example of the 'kind' property for a JSContact Card, specifying the entity type as 'individual'.

```json
"kind": "individual"
```

--------------------------------

### Name with Phonetic and Localization Example

Source: https://jmap.io/spec/rfc9553

Example of a Card object with a name in Traditional Chinese, including phonetic information and localizations for Cantonese.

```json
{
  "@type": "Card",
  "language": "zh-Hant",
  "name": {
    "components": [
      { "kind": "surname", "value": "孫" },
      { "kind": "given", "value": "中山" },
      { "kind": "given2", "value": "文" },
      { "kind": "given2", "value": "逸仙" }
    ]
  },
  "localizations": {
    "yue": {
      "name/phoneticSystem": "jyut",
      "name/phoneticScript": "Latn",
      "name/components/0/phonetic": "syun1",
      "name/components/1/phonetic": "zung1saan1",
      "name/components/2/phonetic": "man4",
      "name/components/3/phonetic": "jat6sin1"
    }
  }
}
```

--------------------------------

### JSContact Card updated Property Example

Source: https://jmap.io/spec/rfc9553

Example of the 'updated' property for a JSContact Card, indicating the last modification date and time.

```json
"updated": "2021-10-31T22:27:10Z"
```

--------------------------------

### Example of intermediate state generation

Source: https://jmap.io/spec/rfc8620

Illustrates how a server might return changes in intermediate states to manage large updates. The client repeatedly calls /changes until hasMoreChanges is false.

```text
A -> B -> C -> D -> E

```

```text
state: "B-D-E"
hasMoreChanges: true

```

```text
state: "B-C-E"
hasMoreChanges: true

```

```text
state: "E"
hasMoreChanges: false

```

--------------------------------

### JSContact Card language Property Example

Source: https://jmap.io/spec/rfc9553

Example of the 'language' property for a JSContact Card, indicating the language tag for text content.

```json
"language": "de-AT"
```
Tokens:
Raw