@dxos/plugin-jmap 0.10.0

package/src/apis/jmap-api.test.ts

@@ -0,0 +1,261 @@
+//
+// 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 { afterEach, beforeEach, vi } from 'vitest';
+
+import { JmapApiError } from '../errors';
+import { JmapCredentials } from '../services';
+import { Jmap, JmapMail } from './index';
+
+const HOST = 'api.fastmail.com';
+const ACCOUNT_ID = 'u9999';
+const API_URL = 'https://api.fastmail.com/jmap/api/';
+
+const SESSION = {
+  apiUrl: API_URL,
+  downloadUrl: 'https://api.fastmail.com/jmap/download/{accountId}/{blobId}/{name}?type={type}',
+  username: 'alice@fastmail.com',
+  primaryAccounts: {
+    'urn:ietf:params:jmap:mail': ACCOUNT_ID,
+    'urn:ietf:params:jmap:submission': ACCOUNT_ID,
+  },
+  accounts: { [ACCOUNT_ID]: { name: 'alice@fastmail.com', isPersonal: true } },
+  capabilities: { 'urn:ietf:params:jmap:core': {}, 'urn:ietf:params:jmap:mail': {} },
+  state: 'cyrus-0',
+};
+
+const TARGET: JmapMail.Target = { apiUrl: API_URL, accountId: ACCOUNT_ID };
+
+const TestLayer = Layer.mergeAll(
+  FetchHttpClient.layer,
+  JmapCredentials.fromValues({ host: HOST, token: 'test-token' }),
+);
+
+type MockRequest = { url: string; method: string; body: any };
+type MockResult = { status?: number; body: unknown };
+
+let respond: (request: MockRequest) => MockResult;
+let originalFetch: typeof globalThis.fetch;
+
+beforeEach(() => {
+  originalFetch = globalThis.fetch;
+  globalThis.fetch = vi.fn(async (...args: Parameters<typeof fetch>): Promise<Response> => {
+    const [input, init] = args;
+    const request = input instanceof Request ? input : new Request(input, init);
+    const text = request.method === 'POST' ? await request.text() : '';
+    const result = respond({ url: request.url, method: request.method, body: text ? JSON.parse(text) : undefined });
+    return new Response(JSON.stringify(result.body ?? {}), {
+      status: result.status ?? 200,
+      headers: { 'content-type': 'application/json' },
+    });
+  });
+});
+
+afterEach(() => {
+  globalThis.fetch = originalFetch;
+  vi.restoreAllMocks();
+});
+
+describe('JMAP API', () => {
+  it.effect(
+    'getSession discovers the well-known URL and returns apiUrl + account',
+    Effect.fnUntraced(function* ({ expect }) {
+      respond = ({ url, method }) => {
+        expect(method).toBe('GET');
+        expect(url).toContain('/.well-known/jmap');
+        return { body: SESSION };
+      };
+      const session = yield* Jmap.getSession;
+      expect(session.apiUrl).toBe(API_URL);
+      expect(session.primaryAccounts['urn:ietf:params:jmap:mail']).toBe(ACCOUNT_ID);
+      expect(session.username).toBe('alice@fastmail.com');
+    }, Effect.provide(TestLayer)),
+  );
+
+  it.effect(
+    'mailboxGet returns folders with roles',
+    Effect.fnUntraced(function* ({ expect }) {
+      respond = ({ body }) => {
+        expect(body.methodCalls[0][0]).toBe('Mailbox/get');
+        return {
+          body: {
+            methodResponses: [
+              [
+                'Mailbox/get',
+                {
+                  accountId: ACCOUNT_ID,
+                  list: [
+                    { id: 'mb-inbox', name: 'Inbox', role: 'inbox' },
+                    { id: 'mb-sent', name: 'Sent', role: 'sent' },
+                  ],
+                },
+                '0',
+              ],
+            ],
+          },
+        };
+      };
+      const result = yield* JmapMail.mailboxGet(TARGET);
+      expect(result.list).toHaveLength(2);
+      expect(result.list.find((folder) => folder.role === 'inbox')?.id).toBe('mb-inbox');
+    }, Effect.provide(TestLayer)),
+  );
+
+  it.effect(
+    'emailQuery sends the filter + sort and returns ids',
+    Effect.fnUntraced(function* ({ expect }) {
+      respond = ({ body }) => {
+        const [name, args] = body.methodCalls[0];
+        expect(name).toBe('Email/query');
+        expect(args.accountId).toBe(ACCOUNT_ID);
+        expect(args.filter).toEqual({ inMailbox: 'mb-inbox' });
+        expect(args.sort).toEqual([{ property: 'receivedAt', isAscending: false }]);
+        expect(args.limit).toBe(50);
+        return {
+          body: { methodResponses: [['Email/query', { accountId: ACCOUNT_ID, ids: ['e1', 'e2'], total: 2 }, '0']] },
+        };
+      };
+      const result = yield* JmapMail.emailQuery(TARGET, {
+        filter: { inMailbox: 'mb-inbox' },
+        sort: [{ property: 'receivedAt', isAscending: false }],
+        limit: 50,
+      });
+      expect(result.ids).toEqual(['e1', 'e2']);
+    }, Effect.provide(TestLayer)),
+  );
+
+  it.effect(
+    'emailGet requests html + text body values and decodes emails',
+    Effect.fnUntraced(function* ({ expect }) {
+      respond = ({ body }) => {
+        const [name, args] = body.methodCalls[0];
+        expect(name).toBe('Email/get');
+        expect(args.ids).toEqual(['e1']);
+        expect(args.fetchTextBodyValues).toBe(true);
+        expect(args.fetchHTMLBodyValues).toBe(true);
+        return {
+          body: {
+            methodResponses: [
+              [
+                'Email/get',
+                {
+                  accountId: ACCOUNT_ID,
+                  list: [
+                    {
+                      id: 'e1',
+                      threadId: 't-e1',
+                      receivedAt: '2026-01-01T00:00:00.000Z',
+                      from: [{ name: 'A', email: 'a@b.com' }],
+                      bodyValues: { body: { value: 'hi' } },
+                      textBody: [{ partId: 'body' }],
+                    },
+                  ],
+                },
+                '0',
+              ],
+            ],
+          },
+        };
+      };
+      const result = yield* JmapMail.emailGet(TARGET, ['e1']);
+      expect(result.list[0].id).toBe('e1');
+      expect(result.list[0].bodyValues?.body?.value).toBe('hi');
+    }, Effect.provide(TestLayer)),
+  );
+
+  it.effect(
+    'submitEmail creates the draft and submission in a single batched request',
+    Effect.fnUntraced(function* ({ expect }) {
+      respond = ({ body }) => {
+        expect(body.using).toContain('urn:ietf:params:jmap:submission');
+        const [setName, setArgs, setId] = body.methodCalls[0];
+        const [subName, subArgs, subId] = body.methodCalls[1];
+        expect(setName).toBe('Email/set');
+        expect(setArgs.create.draft.mailboxIds).toEqual({ 'mb-drafts': true });
+        expect(setArgs.create.draft.keywords).toEqual({ $draft: true, $seen: true });
+        expect(subName).toBe('EmailSubmission/set');
+        expect(subArgs.create.sub.emailId).toBe('#draft');
+        expect(subArgs.onSuccessUpdateEmail['#sub']['mailboxIds/mb-sent']).toBe(true);
+        expect(subArgs.onSuccessUpdateEmail['#sub']['mailboxIds/mb-drafts']).toBeNull();
+        return {
+          body: {
+            methodResponses: [
+              [setName, { accountId: ACCOUNT_ID, created: { draft: { id: 'new-1', threadId: 't-1' } } }, setId],
+              [subName, { accountId: ACCOUNT_ID, created: { sub: { id: 'sub-1' } } }, subId],
+            ],
+          },
+        };
+      };
+      const result = yield* JmapMail.submitEmail(TARGET, {
+        identityId: 'id-1',
+        draftsMailboxId: 'mb-drafts',
+        sentMailboxId: 'mb-sent',
+        draft: { from: [{ email: 'me@x.com' }], to: [{ email: 'you@x.com' }], subject: 'Hi', text: 'Body' },
+      });
+      expect(result.id).toBe('new-1');
+      expect(result.threadId).toBe('t-1');
+    }, Effect.provide(TestLayer)),
+  );
+
+  it.effect(
+    'identityGet lists sending identities',
+    Effect.fnUntraced(function* ({ expect }) {
+      respond = ({ body }) => {
+        const [name, args] = body.methodCalls[0];
+        expect(name).toBe('Identity/get');
+        expect(body.using).toContain('urn:ietf:params:jmap:submission');
+        expect(args.accountId).toBe(ACCOUNT_ID);
+        return {
+          body: {
+            methodResponses: [
+              ['Identity/get', { accountId: ACCOUNT_ID, list: [{ id: 'id-1', email: 'me@x.com' }] }, '0'],
+            ],
+          },
+        };
+      };
+      const result = yield* JmapMail.identityGet(TARGET);
+      expect(result.list[0].email).toBe('me@x.com');
+    }, Effect.provide(TestLayer)),
+  );
+
+  it.effect(
+    'emailSetUpdate patches an email (move to trash)',
+    Effect.fnUntraced(function* ({ expect }) {
+      respond = ({ body }) => {
+        const [name, args] = body.methodCalls[0];
+        expect(name).toBe('Email/set');
+        expect(args.update).toEqual({ e1: { mailboxIds: { 'mb-trash': true } } });
+        return { body: { methodResponses: [['Email/set', { accountId: ACCOUNT_ID, updated: { e1: null } }, '0']] } };
+      };
+      const result = yield* JmapMail.emailSetUpdate(TARGET, 'e1', { mailboxIds: { 'mb-trash': true } });
+      expect(result.updated?.e1).toBeNull();
+    }, Effect.provide(TestLayer)),
+  );
+
+  it.effect(
+    'a 401 status surfaces as a JmapApiError carrying the status',
+    Effect.fnUntraced(function* ({ expect }) {
+      respond = () => ({ status: 401, body: { type: 'about:blank', status: 401 } });
+      const error = yield* Effect.flip(Jmap.getSession);
+      expect(error).toBeInstanceOf(JmapApiError);
+      expect(error.status).toBe(401);
+    }, Effect.provide(TestLayer)),
+  );
+
+  it.effect(
+    'a method-level error response surfaces as a JmapApiError carrying the type',
+    Effect.fnUntraced(function* ({ expect }) {
+      respond = () => ({
+        body: { methodResponses: [['error', { type: 'unknownMethod', description: 'nope' }, '0']] },
+      });
+      const error = yield* Effect.flip(JmapMail.mailboxGet(TARGET));
+      expect(error).toBeInstanceOf(JmapApiError);
+      expect(error.type).toBe('unknownMethod');
+    }, Effect.provide(TestLayer)),
+  );
+});

package/src/capabilities/connector.ts

@@ -0,0 +1,44 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import * as Effect from 'effect/Effect';
+
+import * as Capability from '@dxos/app-framework/Capability';
+import * as Trigger from '@dxos/compute/Trigger';
+import { Type } from '@dxos/echo';
+import * as ConnectorSpec from '@dxos/plugin-connector/ConnectorSpec';
+import * as InboxOperation from '@dxos/plugin-inbox/InboxOperation';
+import * as Mailbox from '@dxos/plugin-inbox/Mailbox';
+import { MAIL_AUTO_SYNC, MAIL_REMOTE_SYNC, MAIL_SYNC_CRON } from '@dxos/plugin-inbox/sync';
+import * as SyncOptions from '@dxos/plugin-inbox/SyncOptions';
+
+import { JMAP_DEFAULT_HOST, JMAP_MAIL_CONNECTOR_ID } from '../constants';
+import { jmapCredentialForm } from './credential-form';
+
+export default Capability.makeModule(
+  Effect.fnUntraced(function* () {
+    return Capability.contribute(ConnectorSpec.Connector, [
+      {
+        id: JMAP_MAIL_CONNECTOR_ID,
+        // Nominal default; the real `AccessToken.source` (host) is captured by the credential form.
+        source: JMAP_DEFAULT_HOST,
+        label: 'JMAP Mail',
+        // Non-OAuth: host + email + Bearer API token, validated against the live session on submit.
+        credentialForm: jmapCredentialForm,
+        sync: {
+          operation: InboxOperation.JmapSync,
+          // What this connector binds — how `Mailbox` discovers it without naming JMAP.
+          targetTypename: Type.getTypename(Mailbox.Mailbox),
+          // Single-target connector (the account inbox): no `getTargets`. The coordinator calls
+          // `materializeTarget` (no remoteTarget) to create the Mailbox, then binds.
+          materializeTarget: InboxOperation.MaterializeJmapTarget,
+          optionsSchema: SyncOptions.SyncOptions,
+          auto: MAIL_AUTO_SYNC,
+          trigger: Trigger.specTimer(MAIL_SYNC_CRON),
+          remote: MAIL_REMOTE_SYNC,
+        },
+      },
+    ]);
+  }),
+);

package/src/capabilities/credential-form.test.ts

@@ -0,0 +1,69 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import { describe, it, test } from '@effect/vitest';
+import * as Effect from 'effect/Effect';
+
+import { Jmap } from '../apis';
+import { JMAP_DEFAULT_HOST } from '../constants';
+import { buildJmapCredential, jmapCredentialForm } from './credential-form';
+
+const session = (username?: string): Jmap.Session => ({
+  apiUrl: 'https://api.fastmail.com/jmap/api/',
+  downloadUrl: 'https://api.fastmail.com/jmap/download/{accountId}/{blobId}/{name}?type={type}',
+  primaryAccounts: { 'urn:ietf:params:jmap:mail': 'u1' },
+  username,
+});
+
+const connector = { id: 'jmap-mail', label: 'JMAP Mail' };
+
+describe('jmapCredentialForm', () => {
+  test('defaults the host to the Fastmail endpoint', ({ expect }) => {
+    expect(jmapCredentialForm.defaultValues?.host).toBe(JMAP_DEFAULT_HOST);
+  });
+
+  test('builds an AccessToken + Connection from the form email', ({ expect }) => {
+    const { accessToken, connection } = buildJmapCredential({
+      host: 'mail.example.com',
+      email: 'me@example.com',
+      token: 'secret',
+      session: session('login@example.com'),
+      connector,
+    });
+    expect(accessToken.source).toBe('mail.example.com');
+    expect(accessToken.account).toBe('me@example.com');
+    expect(accessToken.token).toBe('secret');
+    expect(connection.connectorId).toBe('jmap-mail');
+    expect(connection.name).toBe('JMAP Mail');
+    expect(connection.accessToken).toBeDefined();
+  });
+
+  test('falls back to the session username when the email is blank', ({ expect }) => {
+    const { accessToken } = buildJmapCredential({
+      host: 'api.fastmail.com',
+      email: '',
+      token: 'secret',
+      session: session('login@fastmail.com'),
+      connector,
+    });
+    expect(accessToken.account).toBe('login@fastmail.com');
+  });
+
+  it.effect(
+    'onValidate rejects an empty token before any network call',
+    Effect.fnUntraced(function* ({ expect }) {
+      const { onValidate } = jmapCredentialForm;
+      if (!onValidate) {
+        throw new Error('expected an onValidate hook');
+      }
+      const error = yield* Effect.flip(
+        onValidate({
+          values: { host: JMAP_DEFAULT_HOST, email: 'me@example.com', token: '' },
+          connector: { id: 'jmap', source: JMAP_DEFAULT_HOST },
+        }),
+      );
+      expect(error).toBeInstanceOf(Error);
+    }),
+  );
+});

package/src/capabilities/credential-form.ts

@@ -0,0 +1,113 @@
+//
+// 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 Schema from 'effect/Schema';
+
+import { Format, Obj, Ref } from '@dxos/echo';
+import { AccessToken } from '@dxos/link';
+import * as Connection from '@dxos/plugin-connector/Connection';
+import * as ConnectorSpec from '@dxos/plugin-connector/ConnectorSpec';
+
+import { Jmap } from '../apis';
+import { JMAP_DEFAULT_HOST } from '../constants';
+import { JmapApiError } from '../errors';
+import { JmapCredentials } from '../services';
+
+/**
+ * Manual-credential form for the JMAP connector. JMAP auth is a server-issued Bearer API token
+ * (Fastmail: Settings → Privacy & Security → Integrations), outside any OAuth flow, so the host,
+ * email, and token are collected directly.
+ */
+const JmapCredentialFormSchema = Schema.Struct({
+  host: Schema.String.annotations({
+    title: 'Server',
+    description: 'JMAP server host. The session is discovered at https://<host>/.well-known/jmap.',
+  }),
+  email: Schema.String.annotations({
+    title: 'Email',
+    description: 'Your email address / username on the JMAP server.',
+  }),
+  token: Schema.String.pipe(Format.FormatAnnotation.set(Format.TypeFormat.Password)).annotations({
+    title: 'API token',
+    description: 'A JMAP API token, sent as a Bearer credential.',
+  }),
+});
+
+type JmapCredentialFormValues = Schema.Schema.Type<typeof JmapCredentialFormSchema>;
+
+export const jmapCredentialForm: ConnectorSpec.CredentialForm<JmapCredentialFormValues> = {
+  schema: JmapCredentialFormSchema,
+  defaultValues: { host: JMAP_DEFAULT_HOST, email: '', token: '' },
+  // Validate against the live session before the dialog closes so a wrong host/token fails inline
+  // (with a clear 401 message) instead of creating a Connection that errors on every later sync.
+  onValidate: ({ values }) =>
+    Effect.gen(function* () {
+      const host = values.host.trim();
+      const token = values.token.trim();
+      if (host.length === 0) {
+        return yield* Effect.fail(new Error('Server host is required.'));
+      }
+      if (token.length === 0) {
+        return yield* Effect.fail(new Error('API token is required.'));
+      }
+      yield* fetchSession(host, token);
+    }),
+  onSubmit: ({ values, connector }) =>
+    Effect.gen(function* () {
+      // Trim defensively: onValidate is optional and callers bypass it in tests.
+      const host = values.host.trim();
+      const email = values.email.trim();
+      const token = values.token.trim();
+      const session = yield* fetchSession(host, token);
+      const { accessToken, connection } = buildJmapCredential({ host, email, token, session, connector });
+      return { kind: 'complete' as const, accessToken, connection };
+    }),
+};
+
+/**
+ * Builds the `AccessToken` (source = host, account = form email or session username) and `Connection`
+ * for a validated JMAP credential. Pure (no DB), so the construction is unit-testable.
+ */
+export const buildJmapCredential = ({
+  host,
+  email,
+  token,
+  session,
+  connector,
+}: {
+  host: string;
+  email: string;
+  token: string;
+  session: Jmap.Session;
+  connector: { id?: string; label?: string };
+}) => {
+  const account = email.length > 0 ? email : session.username;
+  const accessToken = Obj.make(AccessToken.AccessToken, {
+    source: host,
+    ...(account ? { account } : {}),
+    token,
+  });
+  const connection = Connection.make({
+    name: connector.label ?? 'JMAP',
+    connectorId: connector.id,
+    accessToken: Ref.make(accessToken),
+  });
+  return { accessToken, connection };
+};
+
+/** Discovers the JMAP session for the given host/token, surfacing a friendly message on 401. */
+const fetchSession = (host: string, token: string) =>
+  Jmap.getSession.pipe(
+    Effect.provide(Layer.mergeAll(FetchHttpClient.layer, JmapCredentials.fromValues({ host, token }))),
+    Effect.mapError((error) =>
+      error instanceof JmapApiError && error.status === 401
+        ? new Error('The JMAP server rejected the token (401). Check the host and API token and try again.')
+        : error instanceof Error
+          ? error
+          : new Error(String(error)),
+    ),
+  );

package/src/capabilities/index.ts

@@ -0,0 +1,24 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import * as ActivationEvents from '@dxos/app-framework/ActivationEvents';
+import * as Capability from '@dxos/app-framework/Capability';
+import * as AppCapability from '@dxos/app-toolkit/AppCapability';
+import * as ConnectorEvents from '@dxos/plugin-connector/ConnectorEvents';
+import * as ConnectorSpec from '@dxos/plugin-connector/ConnectorSpec';
+import * as InboxCapabilities from '@dxos/plugin-inbox/InboxCapabilities';
+
+export const Connector = Capability.lazyModule(
+  'JmapConnector',
+  { provides: [ConnectorSpec.Connector], activatesOn: ConnectorEvents.Start },
+  () => import('./connector'),
+);
+export const MailSend = Capability.lazyModule(
+  'JmapMailSend',
+  { provides: [InboxCapabilities.MailSendOperation] },
+  () => import('./mail-send'),
+);
+export const OperationHandler = AppCapability.operationHandler(() => import('./operation-handler'), {
+  activatesOn: ActivationEvents.Idle,
+});

package/src/capabilities/mail-send.ts

@@ -0,0 +1,21 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import * as Effect from 'effect/Effect';
+
+import * as Capability from '@dxos/app-framework/Capability';
+import * as InboxCapabilities from '@dxos/plugin-inbox/InboxCapabilities';
+import * as InboxOperation from '@dxos/plugin-inbox/InboxOperation';
+
+import { JMAP_MAIL_CONNECTOR_ID } from '../constants';
+
+/** Routes a draft whose mailbox is bound to a JMAP connection to this provider's send operation. */
+export default Capability.makeModule(
+  Effect.fnUntraced(function* () {
+    return Capability.contribute(InboxCapabilities.MailSendOperation, {
+      connectorId: JMAP_MAIL_CONNECTOR_ID,
+      getOperation: () => InboxOperation.JmapSend,
+    });
+  }),
+);

package/src/capabilities/operation-handler.ts

@@ -0,0 +1,16 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import * as Effect from 'effect/Effect';
+
+import * as Capabilities from '@dxos/app-framework/Capabilities';
+import * as Capability from '@dxos/app-framework/Capability';
+
+import { JmapOperationHandlerSet } from '#operations';
+
+export default Capability.makeModule(
+  Effect.fnUntraced(function* () {
+    return Capability.contribute(Capabilities.OperationHandler, JmapOperationHandlerSet);
+  }),
+);

package/src/constants.ts

@@ -0,0 +1,24 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+/** `Connector.id` for the JMAP mail connector (RFC 8620/8621); stored as `Connection.connectorId`. */
+export const JMAP_MAIL_CONNECTOR_ID = 'jmap-mail';
+
+/**
+ * Default JMAP server host pre-filled in the credential form. Fastmail is the canonical JMAP
+ * provider; the session is discovered at `https://${host}/.well-known/jmap`.
+ */
+export const JMAP_DEFAULT_HOST = 'api.fastmail.com';
+
+/**
+ * The provider's origin domain, used as the foreign-key `Meta.keys[].source` on everything this plugin
+ * syncs — messages (the dedup key; see the mapper) and folder {@link Tag}s alike. One string for both
+ * is deliberate: a foreign key is scoped by the object it sits on, so the type already distinguishes a
+ * message key from a tag key, and `Tag.getOrigin` reads it to mark synced tags read-only.
+ *
+ * (Gmail is asymmetric here — its message source is the older `com.google.mail` while its tags carry
+ * `com.google.gmail`. That is left alone deliberately: renaming a persisted message key would orphan
+ * mail. See `Tag.md` §"Origin domain == key source".)
+ */
+export const JMAP_DOMAIN = 'org.ietf.jmap';

package/src/errors.ts

@@ -0,0 +1,38 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import { BaseError, type BaseErrorOptions } from '@dxos/errors';
+
+/**
+ * JMAP request failed: a non-2xx HTTP status, a JMAP problem-details body, or a method-level
+ * `["error", { type, description }, id]` response. `status` carries the HTTP status (when the
+ * failure is transport-level) and `type` the JMAP error type (when method-level) so callers can
+ * recover with `Effect.catchTag` and distinguish auth (401) from other failures.
+ */
+export class JmapApiError extends BaseError.extend('JmapApiError', 'JMAP API request failed.') {
+  constructor(
+    public readonly status: number | undefined,
+    public readonly detail: string,
+    public readonly type?: string,
+    options?: BaseErrorOptions,
+  ) {
+    super({ ...options, context: { ...(options?.context ?? {}), status, detail, type } });
+  }
+}
+
+/** JMAP send payload missing required fields (`to` or body text). */
+export class JmapSendMessageInvalidError extends BaseError.extend(
+  'JmapSendMessageInvalidError',
+  'Missing "to" or content in message.',
+) {}
+
+/** No JMAP identity permits the connection account as a `from` address, so the email cannot be sent. */
+export class JmapSendIdentityNotFoundError extends BaseError.extend(
+  'JmapSendIdentityNotFoundError',
+  'No JMAP identity matches the connection account.',
+) {
+  constructor(account: string | undefined, options?: Omit<BaseErrorOptions, 'context'>) {
+    super({ context: { account }, ...options });
+  }
+}

package/src/index.ts

@@ -0,0 +1,7 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+export * from './constants';
+export * from './errors';
+export * from './meta';

package/src/meta.ts

@@ -0,0 +1,9 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import * as Plugin from '@dxos/app-framework/Plugin';
+
+import config from '../dx.config';
+
+export const meta = Plugin.getMetaFromConfig(config);

package/src/operations/index.ts

@@ -0,0 +1,13 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import * as Operation from '@dxos/compute/Operation';
+import * as OperationHandlerSet from '@dxos/compute/OperationHandlerSet';
+import * as InboxOperation from '@dxos/plugin-inbox/InboxOperation';
+
+export const JmapOperationHandlerSet = OperationHandlerSet.lazy([
+  InboxOperation.MaterializeJmapTarget.pipe(Operation.lazyHandler(() => import('./mail/materialize/handler'))),
+  InboxOperation.JmapSend.pipe(Operation.lazyHandler(() => import('./mail/send'))),
+  InboxOperation.JmapSync.pipe(Operation.lazyHandler(() => import('./mail/sync'))),
+]);