@dxos/plugin-jmap 0.10.0

package/src/operations/mail/mapper.ts

@@ -0,0 +1,191 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import * as Effect from 'effect/Effect';
+
+import { Obj, Ref } from '@dxos/echo';
+import { type Resolver, resolve } from '@dxos/extractor';
+import { log } from '@dxos/log';
+import { ContentBlock, Message, Person } from '@dxos/types';
+
+import { JmapMail } from '../../apis';
+import { JMAP_DOMAIN } from '../../constants';
+
+/**
+ * Result of mapping a JMAP email. `mailboxIds` (the folders the email is in) and `keywords` (the set
+ * flags, e.g. `$flagged`) are propagated separately so the caller can apply the corresponding tags to
+ * the immutable feed Message — mirrors the Gmail mapper's `labelIds`. Both axes are needed because JMAP
+ * splits folder membership (`mailboxIds`) from flags (`keywords`), unlike Gmail's single label list.
+ */
+export type MappedEmail = {
+  message: Message.Message;
+  mailboxIds: readonly string[];
+  keywords: readonly string[];
+};
+
+/** A JMAP email with its raw HTML and/or plaintext body (JMAP delivers decoded values; no markdown). */
+export type DecodedEmail = {
+  raw: JmapMail.Email;
+  html?: string;
+  plain?: string;
+  attachments: readonly AttachmentMetadata[];
+};
+
+/** Metadata for an attachment part (`Email.attachments`, distinct from the `textBody`/`htmlBody` parts). */
+export type AttachmentMetadata = {
+  readonly blobId: string;
+  readonly name?: string;
+  readonly mimeType?: string;
+  readonly size?: number;
+  /** The part's `Content-ID` (angle brackets stripped, if present), if any — matches a `cid:` reference in an HTML body. */
+  readonly contentId?: string;
+};
+
+/** Attachment parts carry a `blobId` to fetch bytes for; parts without one can't be downloaded. */
+const collectAttachments = (attachments: readonly JmapMail.EmailBodyPart[] | undefined): AttachmentMetadata[] =>
+  (attachments ?? []).flatMap((part) =>
+    part.blobId
+      ? [
+          {
+            blobId: part.blobId,
+            name: part.name ?? undefined,
+            mimeType: part.type,
+            size: part.size,
+            // Servers vary on whether `cid` includes the enclosing `<...>`; strip it defensively so it
+            // matches the bare id an HTML body's `cid:` reference uses.
+            contentId: part.cid ? part.cid.replace(/^<|>$/g, '') : undefined,
+          },
+        ]
+      : [],
+  );
+
+/**
+ * Extracts the raw HTML and plaintext bodies from a JMAP email (values fetched via
+ * `fetchHTMLBodyValues`/`fetchTextBodyValues`). Returns `null` when the email has neither. No
+ * HTML→markdown conversion — the markdown/plain views derive from these raw blocks in the component.
+ */
+export const decodeBody = (email: JmapMail.Email): DecodedEmail | null => {
+  const html = getBodyValue(email, email.htmlBody);
+  const plain = getBodyValue(email, email.textBody);
+  if (html === undefined && plain === undefined) {
+    log('jmap decodeBody: dropping email with no extractable body', {
+      id: email.id,
+      htmlBodyParts: email.htmlBody?.length ?? 0,
+      textBodyParts: email.textBody?.length ?? 0,
+      bodyValues: email.bodyValues ? Object.keys(email.bodyValues).length : 0,
+    });
+    return null;
+  }
+  return { raw: email, html, plain, attachments: collectAttachments(email.attachments) };
+};
+
+/**
+ * Builds an ECHO Message from a decoded (already body-normalized) JMAP email and an optional resolved
+ * sender contact. Pure — contact resolution is done by the caller. Returns `null` when the email has
+ * no sender.
+ */
+export const mapToMessage = (decoded: DecodedEmail, contact: Person.Person | undefined): MappedEmail | null => {
+  const { raw: email, html, plain } = decoded;
+  const fromAddress = email.from?.[0];
+  if (!fromAddress) {
+    log('jmap mapToMessage: dropping email with no sender', { id: email.id });
+    return null;
+  }
+
+  // Omit `contact` entirely when unresolved: an explicit `undefined` round-trips to `null` and
+  // fails Message schema validation on queue load (see mapper.test.ts).
+  const sender = {
+    email: fromAddress.email,
+    ...(fromAddress.name ? { name: fromAddress.name } : {}),
+    ...(contact ? { contact: Ref.make(contact) } : {}),
+  };
+
+  // Store the raw HTML and plaintext bodies as separately-typed blocks; the markdown view derives
+  // from the HTML in-component.
+  const blocks: ContentBlock.Text[] = [];
+  if (html !== undefined) {
+    blocks.push({ _tag: 'text', text: html, mimeType: 'text/html' });
+  }
+  if (plain !== undefined) {
+    blocks.push({ _tag: 'text', text: plain, mimeType: 'text/plain' });
+  }
+
+  const echoMessage = Obj.make(Message.Message, {
+    [Obj.Meta]: {
+      keys: [{ id: email.id, source: JMAP_DOMAIN }],
+    },
+
+    created: email.receivedAt,
+    sender,
+    threadId: email.threadId,
+
+    properties: {
+      threadId: email.threadId,
+      // `snippet` is the field inbox UI renders for previews; JMAP's `preview` is its analogue.
+      snippet: email.preview ?? undefined,
+      subject: email.subject ?? undefined,
+      messageId: email.messageId?.[0],
+      inReplyTo: email.inReplyTo?.[0],
+      references: email.references?.join(' '),
+      to: formatAddresses(email.to),
+      cc: formatAddresses(email.cc),
+    },
+
+    blocks,
+  });
+
+  // `keywords` is a `{ [keyword]: true }` set; keep only the keys currently set.
+  const keywords = email.keywords
+    ? Object.entries(email.keywords)
+        .filter(([, set]) => set)
+        .map(([keyword]) => keyword)
+    : [];
+
+  return {
+    message: echoMessage,
+    mailboxIds: email.mailboxIds ? Object.keys(email.mailboxIds) : [],
+    keywords,
+  };
+};
+
+/**
+ * Maps a JMAP email to an ECHO Message, resolving the sender against existing contacts. Composes
+ * {@link decodeBody} → {@link mapToMessage}. Returns `null` when the email has no body or no sender.
+ */
+export const mapEmail: (email: JmapMail.Email) => Effect.Effect<MappedEmail | null, never, Resolver> =
+  Effect.fnUntraced(function* (email) {
+    const decoded = decodeBody(email);
+    if (!decoded) {
+      return null;
+    }
+    const fromAddress = email.from?.[0];
+    const contact = fromAddress ? yield* resolve(Person.Person, { email: fromAddress.email }) : undefined;
+    return mapToMessage(decoded, contact ?? undefined);
+  });
+
+/** Formats a JMAP address as `"Name <email>"`, or just the address when unnamed. */
+const formatAddress = (address: JmapMail.EmailAddress): string =>
+  address.name ? `${address.name} <${address.email}>` : address.email;
+
+/** Joins an address list into a header-style string, or `undefined` when empty. */
+const formatAddresses = (addresses: readonly JmapMail.EmailAddress[] | null | undefined): string | undefined =>
+  addresses && addresses.length > 0 ? addresses.map(formatAddress).join(', ') : undefined;
+
+/**
+ * Returns the first non-empty decoded value among the given body parts (e.g. `email.htmlBody` or
+ * `email.textBody`). `Email/get` is requested with `fetchHTMLBodyValues`/`fetchTextBodyValues`, so the
+ * referenced `bodyValues` are already decoded.
+ */
+const getBodyValue = (
+  email: JmapMail.Email,
+  parts: readonly JmapMail.EmailBodyPart[] | undefined,
+): string | undefined => {
+  for (const part of parts ?? []) {
+    const value = part.partId ? email.bodyValues?.[part.partId]?.value : undefined;
+    if (value && value.trim().length > 0) {
+      return value;
+    }
+  }
+  return undefined;
+};

package/src/operations/mail/materialize/handler.ts

@@ -0,0 +1,41 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import * as Effect from 'effect/Effect';
+
+import { SyncDatabaseMissingError } from '@dxos/app-toolkit';
+import * as Operation from '@dxos/compute/Operation';
+import { Database, Obj, Ref } from '@dxos/echo';
+import * as InboxOperation from '@dxos/plugin-inbox/InboxOperation';
+import * as Mailbox from '@dxos/plugin-inbox/Mailbox';
+
+/**
+ * Eagerly materializes a local Mailbox so the sync cursor's target exists before the cursor is
+ * created. JMAP is a single-target connector (the account inbox), so a fresh Mailbox is always
+ * created; the connection's `accessToken.account` seeds the default name. Mirrors the Gmail
+ * materialize-target.
+ */
+const handler: Operation.WithHandler<typeof InboxOperation.MaterializeJmapTarget> =
+  InboxOperation.MaterializeJmapTarget.pipe(
+    Operation.withHandler(
+      Effect.fnUntraced(function* ({ connection }) {
+        // The operation derives the db from the connection ref's target and provides
+        // `Database.layer(db)` itself (composer's invoker is wired without a `databaseResolver`).
+        const connectionObj = connection.target;
+        const db = connectionObj ? Obj.getDatabase(connectionObj) : undefined;
+        if (!connectionObj || !db) {
+          return yield* Effect.fail(new SyncDatabaseMissingError());
+        }
+
+        return yield* Effect.gen(function* () {
+          const accessToken = yield* Database.load(connectionObj.accessToken);
+          const name = accessToken.account ?? 'Inbox';
+          const created = yield* Database.add(Mailbox.make({ name }));
+          return { target: Ref.make(created) };
+        }).pipe(Effect.provide(Database.layer(db)));
+      }),
+    ),
+  );
+
+export default handler;

package/src/operations/mail/send/handler.ts

@@ -0,0 +1,116 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import * as FetchHttpClient from '@effect/platform/FetchHttpClient';
+import * as Effect from 'effect/Effect';
+
+import * as Operation from '@dxos/compute/Operation';
+import { log } from '@dxos/log';
+import * as InboxOperation from '@dxos/plugin-inbox/InboxOperation';
+import * as SystemTags from '@dxos/plugin-inbox/SystemTags';
+
+import { Jmap, JmapMail } from '../../../apis';
+import { JmapApiError, JmapSendIdentityNotFoundError, JmapSendMessageInvalidError } from '../../../errors';
+import { JmapCredentials } from '../../../services';
+
+const MAIL_ACCOUNT_CAPABILITY = 'urn:ietf:params:jmap:mail';
+
+export default InboxOperation.JmapSend.pipe(
+  Operation.withHandler(({ message, connection: connectionRef }) =>
+    Effect.gen(function* () {
+      log('sending email via jmap', { connection: connectionRef.uri });
+
+      const to = message.properties?.to;
+      const cc = message.properties?.cc;
+      const bcc = message.properties?.bcc;
+      const subject = message.properties?.subject;
+      const inReplyTo = message.properties?.inReplyTo;
+      const references = message.properties?.references;
+      const textBlock = message.blocks.find((block) => block._tag === 'text');
+      const text = textBlock?._tag === 'text' ? textBlock.text : undefined;
+
+      if (!to || !text) {
+        return yield* Effect.fail(new JmapSendMessageInvalidError());
+      }
+
+      const session = yield* Jmap.getSession;
+      const accountId = session.primaryAccounts[MAIL_ACCOUNT_CAPABILITY];
+      if (!accountId) {
+        return yield* Effect.fail(new JmapApiError(undefined, 'JMAP session has no mail account.'));
+      }
+      const target: JmapMail.Target = { apiUrl: session.apiUrl, accountId };
+
+      const credentials = yield* JmapCredentials;
+      const account = credentials.account ?? session.username;
+
+      // The submission requires an identity whose email the server permits as `from`; pick the one
+      // matching the connection account (fall back to the first if the account is unknown).
+      const { list: identities } = yield* JmapMail.identityGet(target);
+      const identity = account
+        ? identities.find((candidate) => candidate.email.toLowerCase() === account.toLowerCase())
+        : identities[0];
+      if (!identity) {
+        return yield* Effect.fail(new JmapSendIdentityNotFoundError(account));
+      }
+
+      const { list: folders } = yield* JmapMail.mailboxGet(target);
+      const drafts = folders.find((folder) => folder.role === 'drafts');
+      const sent = folders.find((folder) => folder.role === 'sent');
+      if (!drafts || !sent) {
+        return yield* Effect.fail(new JmapApiError(undefined, 'JMAP account is missing a Drafts or Sent folder.'));
+      }
+
+      const fromAddress = identity.name ? { email: identity.email, name: identity.name } : { email: identity.email };
+
+      const result = yield* JmapMail.submitEmail(target, {
+        identityId: identity.id,
+        draftsMailboxId: drafts.id,
+        sentMailboxId: sent.id,
+        draft: {
+          from: [fromAddress],
+          to: parseAddressList(to),
+          ...(cc ? { cc: parseAddressList(cc) } : {}),
+          ...(bcc ? { bcc: parseAddressList(bcc) } : {}),
+          ...(subject ? { subject } : {}),
+          ...(inReplyTo ? { inReplyTo: [inReplyTo] } : {}),
+          ...(references ? { references: splitReferences(references) } : {}),
+          text,
+        },
+      });
+
+      log('email sent via jmap', { id: result.id });
+      return {
+        id: result.id,
+        threadId: result.threadId ?? '',
+        // The submission filed the message into the Sent (`sent`-role) folder, which sync maps onto the
+        // canonical `sent` system tag; return that same canonical tag so the caller can tag the local
+        // draft to match the copy that will sync down.
+        sentTag: { ...SystemTags.systemTagKey('sent'), label: SystemTags.SystemTag.sent.label },
+      };
+    }).pipe(Effect.provide(FetchHttpClient.layer), Effect.provide(JmapCredentials.fromConnection(connectionRef))),
+  ),
+  Operation.opaqueHandler,
+);
+
+/** Parses a comma-separated header value into JMAP structured addresses. */
+const parseAddressList = (value: string): { email: string; name?: string }[] =>
+  value
+    .split(',')
+    .map((part) => part.trim())
+    .filter(Boolean)
+    .map(parseAddress);
+
+/** Parses a single `"Name <email>"` (or bare `email`) into a JMAP structured address. */
+const parseAddress = (value: string): { email: string; name?: string } => {
+  const match = value.match(/^\s*(?:"?([^"<]*?)"?\s+)?<([^>]+)>\s*$/);
+  if (match) {
+    const name = match[1]?.trim();
+    const email = match[2].trim();
+    return name ? { email, name } : { email };
+  }
+  return { email: value.trim() };
+};
+
+/** Splits a `References` header (whitespace-separated message ids) into an array. */
+const splitReferences = (value: string): string[] => value.split(/\s+/).filter(Boolean);

package/src/operations/mail/send/index.ts

@@ -0,0 +1,5 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+export { default } from './handler';

package/src/operations/mail/sync/handler.ts

@@ -0,0 +1,52 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import * as FetchHttpClient from '@effect/platform/FetchHttpClient';
+import * as Effect from 'effect/Effect';
+import * as Layer from 'effect/Layer';
+
+import * as Operation from '@dxos/compute/Operation';
+import { Obj } from '@dxos/echo';
+import * as InboxResolver from '@dxos/extractor-lib';
+import { Cursor } from '@dxos/link';
+import { log } from '@dxos/log';
+import * as InboxOperation from '@dxos/plugin-inbox/InboxOperation';
+import { runMailSync } from '@dxos/plugin-inbox/sync';
+
+import { JmapCredentials, JmapMailApi } from '../../../services';
+import { jmapMailSyncProvider } from './sync-provider';
+
+const handler = InboxOperation.JmapSync.pipe(
+  Operation.withHandler(({ binding: bindingRef }) =>
+    Effect.gen(function* () {
+      const bindingObj = bindingRef.target;
+      const db = bindingObj ? Obj.getDatabase(bindingObj) : undefined;
+      if (!bindingObj || !db || !Cursor.isExternal(bindingObj)) {
+        log.warn('jmap sync skipped: missing binding target or database', {
+          hasBinding: Boolean(bindingObj),
+          hasDatabase: Boolean(db),
+        });
+        return { newMessages: 0 };
+      }
+
+      const accessTokenRef = bindingObj.spec.source;
+      // Layer stack, top-down: the provider needs JmapMailApi + Resolver; JmapMailApi.Live needs the
+      // HTTP client + credentials. Chained `Layer.provide` reads as that dependency stack.
+      return yield* runMailSync({ binding: bindingRef }).pipe(
+        Effect.provide(
+          jmapMailSyncProvider().pipe(
+            Layer.provide(InboxResolver.Live),
+            Layer.provide(JmapMailApi.Live),
+            Layer.provide(FetchHttpClient.layer),
+            Layer.provide(JmapCredentials.fromAccessToken(accessTokenRef)),
+          ),
+        ),
+        Effect.withSpan('jmap-sync'),
+      );
+    }),
+  ),
+  Operation.opaqueHandler,
+);
+
+export default handler;

package/src/operations/mail/sync/index.ts

@@ -0,0 +1,7 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+export * from './sync-provider';
+
+export { default } from './handler';

package/src/operations/mail/sync/mapper.test.ts

@@ -0,0 +1,150 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import { describe, it, test } from '@effect/vitest';
+import * as Effect from 'effect/Effect';
+
+import { Obj } from '@dxos/echo';
+import * as InboxResolver from '@dxos/extractor-lib';
+import { Person } from '@dxos/types';
+
+import { JmapMail } from '../../../apis';
+import { JMAP_DOMAIN } from '../../../constants';
+import { decodeBody, mapEmail } from '../mapper';
+
+const makeJmapEmail = (overrides?: Partial<JmapMail.Email>): JmapMail.Email => ({
+  id: 'email-001',
+  threadId: 'thread-001',
+  mailboxIds: { 'mb-inbox': true },
+  keywords: { $seen: true },
+  from: [{ name: 'Alice', email: 'alice@unknown.com' }],
+  to: [{ name: null, email: 'bob@example.com' }],
+  cc: [{ name: 'Carol', email: 'carol@example.com' }],
+  subject: 'Test Subject',
+  receivedAt: '2026-01-15T10:00:00.000Z',
+  preview: 'Hello World preview',
+  messageId: ['<msg-001@unknown.com>'],
+  inReplyTo: ['<parent-001@unknown.com>'],
+  references: ['<ref-1@x.com>', '<ref-2@x.com>'],
+  bodyValues: { body: { value: 'Hello World' } },
+  textBody: [{ partId: 'body', type: 'text/plain' }],
+  ...overrides,
+});
+
+describe('mapEmail', () => {
+  it.effect(
+    'maps a JMAP email to a Message with structured fields and the JMAP foreign key',
+    Effect.fnUntraced(function* ({ expect }) {
+      const result = yield* mapEmail(makeJmapEmail());
+      if (!result) {
+        throw new Error('expected a mapped message');
+      }
+      const message = result.message;
+
+      expect(message.created).toBe('2026-01-15T10:00:00.000Z');
+      expect(message.sender.email).toBe('alice@unknown.com');
+      expect(message.sender.name).toBe('Alice');
+
+      const properties = message.properties;
+      if (properties === undefined) {
+        throw new Error('expected message properties');
+      }
+      expect(properties.subject).toBe('Test Subject');
+      expect(properties.snippet).toBe('Hello World preview');
+      expect(properties.messageId).toBe('<msg-001@unknown.com>');
+      expect(properties.inReplyTo).toBe('<parent-001@unknown.com>');
+      expect(properties.references).toBe('<ref-1@x.com> <ref-2@x.com>');
+      expect(properties.to).toBe('bob@example.com');
+      expect(properties.cc).toBe('Carol <carol@example.com>');
+
+      const block = message.blocks[0];
+      if (block?._tag !== 'text') {
+        throw new Error('expected a text block');
+      }
+      expect(block.text).toContain('Hello World');
+
+      const foreignId = Obj.getMeta(message).keys.find((key) => key.source === JMAP_DOMAIN)?.id;
+      expect(foreignId).toBe('email-001');
+
+      expect(result.mailboxIds).toEqual(['mb-inbox']);
+      // Active keywords are surfaced verbatim; the provider maps them onto canonical system tags.
+      expect(result.keywords).toEqual(['$seen']);
+    }, Effect.provide(InboxResolver.Mock())),
+  );
+
+  it.effect(
+    'omits sender.contact entirely when no contact resolves',
+    Effect.fnUntraced(function* ({ expect }) {
+      const result = yield* mapEmail(makeJmapEmail());
+      if (!result) {
+        throw new Error('expected a mapped message');
+      }
+
+      // An explicit `contact: undefined` round-trips to `null` (protobuf Struct) and fails Message
+      // schema validation on queue load; the key must be absent, not undefined.
+      expect('contact' in result.message.sender).toBe(false);
+    }, Effect.provide(InboxResolver.Mock())),
+  );
+
+  it.effect(
+    'returns null when the email has no sender or no body',
+    Effect.fnUntraced(function* ({ expect }) {
+      const noSender = yield* mapEmail(makeJmapEmail({ from: null }));
+      expect(noSender).toBeNull();
+
+      const noBody = yield* mapEmail(makeJmapEmail({ bodyValues: undefined, textBody: undefined }));
+      expect(noBody).toBeNull();
+    }, Effect.provide(InboxResolver.Mock())),
+  );
+
+  it.effect(
+    'resolves the sender contact when the resolver finds a Person',
+    Effect.fnUntraced(
+      function* ({ expect }) {
+        const result = yield* mapEmail(makeJmapEmail());
+        if (!result) {
+          throw new Error('expected a mapped message');
+        }
+        expect('contact' in result.message.sender).toBe(true);
+      },
+      Effect.provide(
+        InboxResolver.Mock({
+          people: [Obj.make(Person.Person, { emails: [{ value: 'alice@unknown.com' }] })],
+        }),
+      ),
+    ),
+  );
+});
+
+describe('decodeBody attachments', () => {
+  test('collects attachment metadata from Email.attachments', ({ expect }) => {
+    const email = makeJmapEmail({
+      attachments: [
+        { blobId: 'blob-1', name: 'photo.png', type: 'image/png', size: 1234 },
+        { partId: 'body-2', type: 'text/plain' }, // a body part with no blobId can't be downloaded.
+      ],
+    });
+    const decoded = decodeBody(email);
+    expect(decoded?.attachments).toEqual([{ blobId: 'blob-1', name: 'photo.png', mimeType: 'image/png', size: 1234 }]);
+  });
+
+  test('is empty when the email has no attachments', ({ expect }) => {
+    const decoded = decodeBody(makeJmapEmail());
+    expect(decoded?.attachments).toEqual([]);
+  });
+
+  test('extracts a Content-ID for inline attachments, stripping enclosing angle brackets if present', ({ expect }) => {
+    const email = makeJmapEmail({
+      attachments: [
+        { blobId: 'blob-1', name: 'signature.png', type: 'image/png', size: 999, cid: '<ii_mrcqn4871>' },
+        { blobId: 'blob-2', name: 'bare-cid.png', type: 'image/png', size: 111, cid: 'bare-id' },
+      ],
+    });
+    const decoded = decodeBody(email);
+    expect(decoded?.attachments).toEqual([
+      { blobId: 'blob-1', name: 'signature.png', mimeType: 'image/png', size: 999, contentId: 'ii_mrcqn4871' },
+      { blobId: 'blob-2', name: 'bare-cid.png', mimeType: 'image/png', size: 111, contentId: 'bare-id' },
+    ]);
+  });
+});

package/src/operations/mail/sync/sync-e2e.test.ts

@@ -0,0 +1,63 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import * as FetchHttpClient from '@effect/platform/FetchHttpClient';
+import { describe, it } from '@effect/vitest';
+import * as Effect from 'effect/Effect';
+import * as Layer from 'effect/Layer';
+import * as Predicate from 'effect/Predicate';
+
+import * as InboxResolver from '@dxos/extractor-lib';
+
+import { Jmap, JmapMail } from '../../../apis';
+import { JmapCredentials } from '../../../services';
+import { mapEmail } from '../mapper';
+
+/**
+ * Live JMAP test against a real server (Fastmail by default). Gated on `JMAP_TOKEN`, mirroring the
+ * Gmail `GOOGLE_ACCESS_TOKEN` gate. To run:
+ *
+ *   export JMAP_TOKEN="<fastmail api token>"   # Settings → Privacy & Security → Integrations
+ *   export JMAP_HOST="api.fastmail.com"        # optional; defaults to api.fastmail.com
+ *   pnpm vitest sync-e2e.test.ts
+ */
+const HOST = process.env.JMAP_HOST ?? 'api.fastmail.com';
+const TOKEN = process.env.JMAP_TOKEN;
+
+const TestLayer = Layer.mergeAll(
+  FetchHttpClient.layer,
+  JmapCredentials.fromValues({ host: HOST, token: TOKEN ?? '' }),
+  InboxResolver.Mock(),
+);
+
+describe.runIf(TOKEN)('JMAP live', { timeout: 30_000 }, () => {
+  it.effect(
+    'discovers the session, queries the inbox, and maps messages',
+    Effect.fnUntraced(function* ({ expect }) {
+      const session = yield* Jmap.getSession;
+      const accountId = session.primaryAccounts['urn:ietf:params:jmap:mail'];
+      if (!accountId) {
+        throw new Error('JMAP session has no mail account');
+      }
+      const target: JmapMail.Target = { apiUrl: session.apiUrl, accountId };
+
+      const { list: folders } = yield* JmapMail.mailboxGet(target);
+      const inbox = folders.find((folder) => folder.role === 'inbox');
+      if (!inbox) {
+        throw new Error('JMAP account has no inbox');
+      }
+
+      const { ids } = yield* JmapMail.emailQuery(target, {
+        filter: { inMailbox: inbox.id },
+        sort: [{ property: 'receivedAt', isAscending: false }],
+        limit: 5,
+      });
+      const { list: emails } = yield* JmapMail.emailGet(target, ids);
+      const mapped = (yield* Effect.forEach(emails, (email) => mapEmail(email))).filter(Predicate.isNotNullable);
+
+      console.log(`JMAP live: ${folders.length} folders, ${ids.length} inbox ids, ${mapped.length} mapped messages`);
+      expect(Array.isArray(ids)).toBe(true);
+    }, Effect.provide(TestLayer)),
+  );
+});