# useDocyrusEmailComposer
URL: /docs/native/hooks/use-docyrus-email-composer

Wires the native EmailComposer to the Docyrus messaging API — sender accounts, @ mention users and the send mutation, with composer state managed for you.

## Installation

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

**Dependencies:**
- [@tanstack/react-query](https://www.npmjs.com/package/@tanstack/react-query)
- [@docyrus/api-client](https://www.npmjs.com/package/@docyrus/api-client)

A verbatim port of the web hook (same options, result and query keys). It fetches `GET /v1/messaging/email/accounts` for the From picker and auto-selects the first user-accessible account, fetches `GET /v1/users` once for `@` mentions (client-side filtering), and sends through `POST /v1/messaging/email/accounts/{accountId}/send`. It returns `composerProps` to spread onto [rn-email-composer](/docs/native/docyrus/email-composer). Both endpoints need the `Messaging.Email.Send` scope, and a `QueryClientProvider` must be mounted above it.

## Usage

```tsx
import { EmailComposer } from '@/components/docyrus-native/email-composer';
import { useDocyrusEmailComposer } from '@/hooks/docyrus-native/use-docyrus-email-composer';

function ReplyComposer({ client, to }) {
  const { composerProps, send, attachments } = useDocyrusEmailComposer({ client, initialTo: to });

  return (
    <EmailComposer
      {...composerProps}
      attachments={attachments}
      onSend={async () => {
        const result = await send({ attachments: [{ filePath: uploaded.fullPath, fileName: 'quote.pdf' }] });

        console.log(result.accepted, result.rejected);
      }} />
  );
}
```

`send(overrides)` takes storage-backed attachments (`{ filePath, fileName?, mimeType? }`) — upload the picked `NativeFile` to Docyrus storage first. The composer's own `attachments` (`{ name, size }`) are display metadata only.

## API Reference

### UseDocyrusEmailComposerOptions

| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `client` | `RestApiClient` | - | Authenticated REST client (required) |
| `initialTo` / `initialCc` / `initialBcc` / `initialReplyTo` | `string[]` | `[]` | Initial recipients |
| `initialSubject` | `string` | `''` | Initial subject |
| `initialBody` | `string` | `''` | Initial HTML body |
| `initialAccountId` | `string` | first accessible | Account to preselect |
| `resetOnSendSuccess` | `boolean` | `true` | Clear recipients / subject / body / attachments after a send |
| `enabled` | `boolean` | `true` | Toggle the queries |
| `sendAsUser` | `boolean` | - | Default `sendAsUser` for every send |
| `listAccountsEndpoint` | `string` | `/v1/messaging/email/accounts` | Accounts endpoint |
| `sendEndpoint` | `string` | `/v1/messaging/email/accounts/{accountId}/send` | Send endpoint |
| `mentions` | `boolean` | `true` | Fetch `/v1/users` for mentions |
| `mentionUsers` | `EmailComposerMentionUser[]` | - | Explicit mention users (skips the fetch) |
| `listUsersEndpoint` | `string` | `/v1/users` | Users endpoint |
| `slashCommands` | `EmailComposerSlashCommand[]` | - | Passed through to the composer |

### UseDocyrusEmailComposerResult

| Field | Type | Description |
|-------|------|-------------|
| `composerProps` | `Pick<EmailComposerProps, …>` | accounts, selection, to / cc / bcc, subject, body, mentionUsers, slashCommands, onSend, sending |
| `accounts` / `selectedAccount` | `DocyrusEmailAccount[]` / `DocyrusEmailAccount \| null` | Raw account DTOs |
| `setSelectedAccountId` | `(id: string) => void` | Change the account |
| `isLoadingAccounts` / `accountsError` / `refetchAccounts` | | Accounts query state |
| `mentionUsers` | `EmailComposerMentionUser[]` | Resolved mention users |
| `to` / `cc` / `bcc` / `replyTo` / `subject` / `body` / `attachments` + setters | | Composer state |
| `send` | `(overrides?: DocyrusEmailSendOverrides) => Promise<DocyrusEmailSendResult>` | Send |
| `isSending` / `sendError` / `lastSendResult` | | Mutation state |
| `reset` | `() => void` | Restore the initial values |

### Types

| Type | Description |
|------|-------------|
| `DocyrusEmailAccount` | Account DTO (`kind`, `provider`, `providerSlug`, `isUserAccessible`, `allowOverrideName`, `allowOverrideEmail`, `createdOn`) |
| `DocyrusEmailAttachment` | `{ filePath, fileName?, mimeType? }` |
| `DocyrusEmailSendOverrides` | Per-send `to`, `cc`, `bcc`, `replyTo`, `subject`, `body`, `sendAsUser`, `attachments`, `accountId` |
| `DocyrusEmailSendResult` | `{ messageId, provider, accepted, rejected }` |
| `DocyrusEmailProvider` | `'aws' \| 'smtp' \| 'mailgun' \| 'resend' \| 'microsoft-graph' \| 'gmail'` |