useDocyrusEmailComposer

Installation

pnpm dlx @docyrus/cli add @docyrus/hooks-use-docyrus-email-composer

pnpm add @docyrus/api-client @tanstack/react-query

The hook needs an authenticated RestApiClient from @docyrus/api-client and a QueryClientProvider from @tanstack/react-query somewhere above your component tree. The access token must carry the Messaging.Email.Send scope — otherwise both the list-accounts and send calls return 403 insufficient_scope.

Overview

useDocyrusEmailComposer is the Docyrus-backed companion to EmailComposer. It does three things:

• Loads sender accounts — GET /v1/messaging/email/accounts returns both shared tenant accounts (tenant_email_configuration) and the caller's own connected OAuth mailboxes (Microsoft / Google).
• Manages composer state — to, cc, bcc, subject, body, plus the currently selected account id. State persists across re-renders and resets after a successful send (toggle via resetOnSendSuccess).
• Sends through the picked account — POST /v1/messaging/email/accounts/{accountId}/send returns { messageId, provider, accepted, rejected }. Per-call overrides let you set sendAsUser, storage-backed attachments, or replyTo without touching the composer state.

The first user-accessible account is auto-selected once the list resolves, so consumers don't have to wait for the user to pick before the composer becomes interactive.

Usage

Default integration

'use client';

import { useDocyrusAuth } from '@docyrus/signin';

import { EmailComposer } from '@docyrus/ui/components/email-composer';
import {
  useDocyrusEmailComposer
} from '@docyrus/ui/library/hooks/use-docyrus-email-composer';

export function SendEmailDialog({ onClose }: { onClose: () => void }) {
  const { client } = useDocyrusAuth();

  if (!client) return null;

  const composer = useDocyrusEmailComposer({
    client,
    initialTo: ['customer@example.com'],
    initialSubject: 'Following up on your order'
  });

  return (
    <EmailComposer
      {...composer.composerProps}
      onDiscard={onClose} />
  );
}

composerProps spreads the wiring for the From dropdown, recipient fields, subject, body, and the onSend handler. The composer's built-in Send button fires the hook's mutation; no glue required.

Sending with sendAsUser

For tenant accounts that allow it, sendAsUser: true overrides the From name/address with the authenticated user's identity at the API layer (subject to each account's allowOverrideName / allowOverrideEmail flags).

const composer = useDocyrusEmailComposer({
  client,
  sendAsUser: true // forwarded with every send call
});

Or override it per call:

await composer.send({ sendAsUser: true });

Storage-backed attachments

The composer's local EmailAttachment carries { name, size } only — it cannot be transmitted as-is, because the send endpoint expects files that already live in Docyrus storage. Upload first, then hand the storage path(s) to send():

await composer.send({
  attachments: [
    { filePath: 'tenant-files/invoices/inv-1234.pdf', fileName: 'invoice.pdf', mimeType: 'application/pdf' }
  ]
});

Reading the response

lastSendResult carries the latest server response so you can surface rejected recipients:

{composer.lastSendResult?.rejected.length > 0 && (
  <p>The provider rejected: {composer.lastSendResult.rejected.join(', ')}</p>
)}

Account selection

The dropdown surfaces every account returned by the API:

Entries with isUserAccessible: false are rendered disabled in the dropdown — they exist in the tenant configuration but the current user can't send through them.

The hook auto-selects the first isUserAccessible: true account on first load. Override via initialAccountId or by calling setSelectedAccountId(id).

API Reference

useDocyrusEmailComposer(options)

Return value

send(overrides?)

Every field is optional — anything omitted falls back to current composer state.

Type Exports

Error handling

accountsError and sendError surface the underlying API failures verbatim. Common ones: