Introduction

Installation

Install the library using a package manager:

pnpm

pnpm add json-meta-client

npm

npm add json-meta-client

yarn

yarn add json-meta-client

bun

bun add json-meta-client

deno

deno add npm:json-meta-client

Or install it using a module script:

Script

<script type="module">
  import { JsonMetaClient } from "https://unpkg.com/[email protected]/dist/index.js";
</script>

Import Map

<html>
  <head>
    <script type="importmap">
      {
        "imports": {
          "json-meta-client": "https://unpkg.com/[email protected]/dist/index.js"
        }
      }
    </script>
  </head>
  <body>
    <script type="module">
      import { JsonMetaClient } from "json-meta-client";
    </script>
  </body>
</html>

Configuration

Configure a client with authentication, a session URL, and capabilities:

import { JsonMetaClient } from "json-meta-client";

const client = new JsonMetaClient({
  auth: "<token>",
  sessionUrl: "<server>/.well-known/jmap",
  capabilities: ["mail", "submission"],
});

Pass a string as auth to send it as a Bearer token. Clients also support Basic authentication with auth: { username, password }.

For other kinds of authentication (e.g. a proxy header), a custom callback can be used to modify fetch requests as needed. See Authentication for more examples.

Usage

Find the inbox:

example.ts

const mailboxes = await client.api.Mailbox.query({
  filter: { role: "inbox" },
  limit: 1,
});

const inboxId = mailboxes.ids[0]!;

request.json

{
  "using": [
    "urn:ietf:params:jmap:core",
    "urn:ietf:params:jmap:mail"
  ],
  "methodCalls": [
    [
      "Mailbox/query",
      {
        "filter": { "role": "inbox" },
        "limit": 1,
        "accountId": "<accountId>"
      },
      "Mailbox/query::e64dc905"
    ]
  ]
}

Get the first ten unread emails in the inbox:

example.ts

const query = client.api.Email.query({
  filter: { inMailbox: inboxId },
  limit: 10,
});

const emails = await client.api.Email.get({
  ids: query.resultRef("/ids"),
  properties: ["id", "to", "from", "subject", "sentAt"],
});

for (const email of emails.list) {
  // ...
}

request.json

{
  "using": [
    "urn:ietf:params:jmap:core",
    "urn:ietf:params:jmap:mail"
  ],
  "methodCalls": [
    [
      "Email/query",
      {
        "filter": { "inMailbox": "<inboxId>" },
        "limit": 10,
        "accountId": "<accountId>"
      },
      "Email/query::d1ca7ea5"
    ],
    [
      "Email/get",
      {
        "#ids": {
          "name": "Email/query",
          "resultOf": "Email/query::d1ca7ea5",
          "path": "/ids"
        },
        "properties": [
          "id",
          "to",
          "from",
          "subject",
          "sentAt"
        ],
        "accountId": "<accountId>"
      },
      "Email/get::a4f7a29b"
    ]
  ]
}

Next Steps

I want to...	Read
Make JMAP requests	Method Calls
Listen for state changes	Events
Upload and download files	Blobs
Do things the right way™	Best Practices
Test with this library	Testing
Understand the API	API
Handle failures	Errors
Understand how method calls are batched	Batching
Define custom capabilities	Extending
Hook into the request lifecycle	Hooks