Skip to main content
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 for the setup walkthrough.

​
Mailboxes

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

​
List mailboxes

GET /admin/external/mailboxes
Authorization: Bearer <admin-pat>

​
Create a mailbox

POST /admin/external/mailboxes
Authorization: Bearer <admin-pat>
Content-Type: application/json
​
body.name
string
required
Display name for the mailbox.
​
body.address
string
required
The inbound email address this mailbox handles (e.g. support@support.example.com).
​
body.domainId
string
required
Default domain to route matched emails to as work item conversations.

​
Update a mailbox

PATCH /admin/external/mailboxes/:id
Authorization: Bearer <admin-pat>
Content-Type: application/json

​
Delete a mailbox

DELETE /admin/external/mailboxes/:id
Authorization: Bearer <admin-pat>
Deleting a mailbox removes all routing rules associated with it. Emails arriving at the mailbox address will no longer be routed to work items.

​
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

GET /admin/external/mailboxes/:id/routing-rules
Authorization: Bearer <admin-pat>

​
Create a routing rule

POST /admin/external/mailboxes/:id/routing-rules
Authorization: Bearer <admin-pat>
Content-Type: application/json
​
body.matchField
string
required
The email field to match against: from, to, subject, or body.
​
body.matchValue
string
required
The value or pattern to match.
​
body.domainId
string
required
Domain to route matching emails to.
​
body.priority
number
Rule evaluation order. Lower numbers are evaluated first.

​
Update a routing rule

PATCH /admin/external/mailboxes/:id/routing-rules/:ruleId
Authorization: Bearer <admin-pat>
Content-Type: application/json

​
Delete a routing rule

DELETE /admin/external/mailboxes/:id/routing-rules/:ruleId
Authorization: Bearer <admin-pat>

​
Email provider

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

GET /admin/external/email/domains
Authorization: Bearer <admin-pat>

​
Provision a domain

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

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

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

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

GET /admin/external/email/webhooks
Authorization: Bearer <admin-pat>

​
Provision a webhook

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

POST /admin/external/email/webhooks/:id/refresh
Authorization: Bearer <admin-pat>

​
Inbound email webhook

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.
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.