> ## 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 API

> Manage mailboxes, routing rules, and email infrastructure via the API.

OpenIndex routes inbound email to work item conversations through mailboxes and routing rules. Email infrastructure (receiving domains and webhooks) is provisioned through Resend. All admin email endpoints require an `admin`-scoped token.

See [Email Infrastructure](/configuration/email-infrastructure) for the setup walkthrough.

## Mailboxes

Mailboxes define the default routing behavior for inbound email arriving at a provisioned receiving domain.

### List mailboxes

```bash theme={null}
GET /admin/external/mailboxes
Authorization: Bearer <admin-pat>
```

### Create a mailbox

```bash theme={null}
POST /admin/external/mailboxes
Authorization: Bearer <admin-pat>
Content-Type: application/json
```

<ParamField path="body.name" type="string" required>
  Display name for the mailbox.
</ParamField>

<ParamField path="body.address" type="string" required>
  The inbound email address this mailbox handles (e.g. `support@support.example.com`).
</ParamField>

<ParamField path="body.domainId" type="string" required>
  Default domain to route matched emails to as work item conversations.
</ParamField>

### Update a mailbox

```bash theme={null}
PATCH /admin/external/mailboxes/:id
Authorization: Bearer <admin-pat>
Content-Type: application/json
```

### Delete a mailbox

```bash theme={null}
DELETE /admin/external/mailboxes/:id
Authorization: Bearer <admin-pat>
```

<Warning>
  Deleting a mailbox removes all routing rules associated with it. Emails arriving at the mailbox address will no longer be routed to work items.
</Warning>

## Routing rules

Routing rules override a mailbox's default domain routing based on inbound email match criteria. Rules are evaluated in order; the first match wins.

### List routing rules

```bash theme={null}
GET /admin/external/mailboxes/:id/routing-rules
Authorization: Bearer <admin-pat>
```

### Create a routing rule

```bash theme={null}
POST /admin/external/mailboxes/:id/routing-rules
Authorization: Bearer <admin-pat>
Content-Type: application/json
```

<ParamField path="body.matchField" type="string" required>
  The email field to match against: `from`, `to`, `subject`, or `body`.
</ParamField>

<ParamField path="body.matchValue" type="string" required>
  The value or pattern to match.
</ParamField>

<ParamField path="body.domainId" type="string" required>
  Domain to route matching emails to.
</ParamField>

<ParamField path="body.priority" type="number">
  Rule evaluation order. Lower numbers are evaluated first.
</ParamField>

### Update a routing rule

```bash theme={null}
PATCH /admin/external/mailboxes/:id/routing-rules/:ruleId
Authorization: Bearer <admin-pat>
Content-Type: application/json
```

### Delete a routing rule

```bash theme={null}
DELETE /admin/external/mailboxes/:id/routing-rules/:ruleId
Authorization: Bearer <admin-pat>
```

## Email provider

```bash theme={null}
GET /admin/external/email/provider
Authorization: Bearer <admin-pat>
```

Returns the Resend account and provider state for your deployment. Use this to verify your Resend API key is configured correctly before provisioning domains or webhooks.

## Email domains

Receiving domains are provisioned in Resend and configured with DNS records to accept inbound email.

### List email domains

```bash theme={null}
GET /admin/external/email/domains
Authorization: Bearer <admin-pat>
```

### Provision a domain

```bash theme={null}
POST /admin/external/email/domains/provision
Authorization: Bearer <admin-pat>
Content-Type: application/json

{
  "name": "support.example.com"
}
```

Returns the domain ID and DNS records to configure at your DNS provider.

### Refresh domain state

```bash theme={null}
POST /admin/external/email/domains/:id/refresh
Authorization: Bearer <admin-pat>
```

Pulls the latest state for this domain from Resend, including current DNS verification status.

### Verify a domain

```bash theme={null}
POST /admin/external/email/domains/:id/verify
Authorization: Bearer <admin-pat>
```

Triggers a DNS verification check in Resend. Run this after adding the required DNS records.

### Delete a domain

```bash theme={null}
DELETE /admin/external/email/domains/:id
Authorization: Bearer <admin-pat>
```

## Webhooks

Inbound email webhooks forward received messages from Resend to your OpenIndex deployment.

### List webhooks

```bash theme={null}
GET /admin/external/email/webhooks
Authorization: Bearer <admin-pat>
```

### Provision a webhook

```bash theme={null}
POST /admin/external/email/webhooks/provision
Authorization: Bearer <admin-pat>
```

Registers the inbound email webhook endpoint with Resend. OpenIndex receives inbound emails at `POST /webhooks/resend/email-received`.

### Refresh webhook state

```bash theme={null}
POST /admin/external/email/webhooks/:id/refresh
Authorization: Bearer <admin-pat>
```

## Inbound email webhook

```bash theme={null}
POST /webhooks/resend/email-received
```

This endpoint is called by Resend when an inbound email arrives at your provisioned receiving domain. OpenIndex verifies the payload signature using `RESEND_WEBHOOK_SECRET` and routes the email to the matching work item conversation.

<Note>
  You do not call this endpoint directly. Configure your Resend account to forward inbound email to this URL by using `POST /admin/external/email/webhooks/provision`.
</Note>