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

> Provision email domains and webhooks for inbound email operations.

OpenIndex uses Resend-backed email infrastructure to handle both outbound conversation email and inbound email routing. To receive inbound email on a custom domain (e.g. `support.example.com`), you provision a receiving domain and a webhook through the admin API.

## Prerequisites

Set the following environment variables before provisioning:

* `AUTH_RESEND_KEY` — your Resend API key
* `RESEND_WEBHOOK_SECRET` — webhook signing secret from Resend

See [environment variables](/configuration/environment) for details on each variable.

## Setup steps

<Steps>
  <Step title="Get email provider info">
    Check the current provider status before provisioning:

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

    This returns the Resend account details and current provisioning state associated with your deployment.
  </Step>

  <Step title="Provision a receiving domain">
    Create a new receiving domain. OpenIndex will provision the domain in Resend and return DNS records for you to add to your DNS provider.

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

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

    The response includes the domain ID and any DNS records required for verification.

    **Via CLI:**

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

  <Step title="Add DNS records">
    Add the DNS records returned in the provisioning response to your DNS provider. Records typically include MX and TXT entries for the subdomain.

    DNS propagation can take up to 48 hours, though it usually completes within a few minutes.
  </Step>

  <Step title="Verify the domain">
    Once DNS records are in place, trigger verification:

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

    Resend will check the DNS records and confirm the domain is ready to receive email.
  </Step>

  <Step title="Provision an inbound webhook">
    Set up the inbound webhook so Resend forwards received email to your OpenIndex deployment:

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

    OpenIndex registers the webhook endpoint (`POST /webhooks/resend/email-received`) with Resend and stores the webhook configuration.
  </Step>
</Steps>

## Managing existing resources

### Refresh domain or webhook state

If your Resend state becomes out of sync, refresh it to pull the latest status:

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

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

### List provisioned resources

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

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

### Delete a domain

<Warning>
  Deleting a receiving domain stops email delivery for that domain. Any mailboxes routing to the domain will stop receiving inbound messages.
</Warning>

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

## How inbound email flows

Once your domain and webhook are provisioned:

1. An email arrives at an address on your receiving domain (e.g. `support@support.example.com`).
2. Resend forwards the email to `POST /webhooks/resend/email-received` on your deployment.
3. OpenIndex verifies the payload signature using `RESEND_WEBHOOK_SECRET`.
4. The email is normalized into a conversation and matched to a work item based on your mailbox routing rules.

See the [Email API](/api/email) reference for how to configure mailboxes and routing rules.