> ## Documentation Index
> Fetch the complete documentation index at: https://docs.orca.0-9.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Email Operations

> Set up mailboxes, routing rules, and inbound email conversations in OpenIndex.

OpenIndex supports external email conversations linked directly to work items. Inbound email is normalized into a conversation record and can attach to an existing work item or create a new one through routing rules. Outbound replies go through the same conversation thread.

<Note>
  Email infrastructure setup is an admin-only operation. You need instance-admin access to provision receiving domains, mailboxes, and webhooks.
</Note>

***

## How email works in OpenIndex

```
Inbound email → Resend receiving domain → inbound webhook → Convex
→ mailbox routing rules → conversation → work item
```

Outbound replies follow the reverse path. All conversations, participants, and messages are stored as first-class records and can be accessed through the work item they are linked to.

***

## Setting up email infrastructure

Before creating mailboxes, an admin must provision the receiving email domain and configure the inbound webhook.

<Steps>
  <Step title="Provision a receiving domain">
    ```bash theme={null}
    POST /admin/external/email/domains/provision
    ```

    Via CLI:

    ```bash theme={null}
    oi settings external email domains provision --name support.example.com
    ```
  </Step>

  <Step title="Verify the domain">
    After adding the required DNS records, verify the domain:

    ```bash theme={null}
    POST /admin/external/email/domains/:id/verify
    ```
  </Step>

  <Step title="Set up the inbound webhook">
    ```bash theme={null}
    POST /admin/external/email/webhooks/provision
    ```

    This registers the Resend inbound webhook so that email received at your domain triggers the Convex processing pipeline.
  </Step>
</Steps>

To check the current state of your email infrastructure:

```bash theme={null}
oi settings external email provider get
oi settings external email domains list
oi settings external email webhooks list
```

***

## Creating a mailbox

A mailbox defines an inbound email address and its default routing target within a domain.

```bash theme={null}
POST /admin/external/mailboxes
```

To view existing mailboxes:

```bash theme={null}
oi settings external mailboxes list
```

***

## Configuring routing rules

Routing rules let you direct inbound email to specific workflows or domains based on match criteria. Rules are attached to a mailbox.

```bash theme={null}
POST /admin/external/mailboxes/:id/routing-rules
```

To view routing rules for a mailbox:

```bash theme={null}
oi settings external mailboxes routing-rules list support@company.com
```

<Tip>
  Routing rules can fan a single inbound address into multiple workflows within the mailbox domain based on sender, subject, or other match criteria.
</Tip>

***

## How inbound email becomes a conversation

When an email arrives at a provisioned address:

1. Resend forwards it to the inbound webhook at `/webhooks/resend/email-received`.
2. Convex normalizes the message into a `conversations` record with participants and messages.
3. If a routing rule matches, the conversation is linked to a work item in the target domain and workflow.
4. The work item's conversation thread is updated with the inbound message.

***

## Sending an outbound message

To send a reply from a work item's conversation thread:

```bash theme={null}
POST /browse/:key/conversation/send
```

This sends an email to the conversation participants through the provisioned mailbox address.

***

## Viewing a work item's conversation

```bash theme={null}
GET /browse/:key/conversation
```

This returns the full conversation thread for the work item, including all inbound and outbound messages and participant records.

***

## Comment visibility

Comments on a work item have an `internal` or `external` visibility setting. External comments are included in the outbound email thread visible to conversation participants.

```bash theme={null}
# Internal comment (default) — not visible to external participants
oi work-item comment create ABC-123 --body "Internal note for the team" --visibility internal

# External comment — visible in the email thread
oi work-item comment create ABC-123 --body "Update for customer" --visibility external
```

Use external visibility when you want your comment to appear in the next outbound email to the conversation thread. Use internal visibility for notes that should stay within your team.