Skip to main content
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.
Email infrastructure setup is an admin-only operation. You need instance-admin access to provision receiving domains, mailboxes, and webhooks.

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

Provision a receiving domain

POST /admin/external/email/domains/provision
Via CLI:
oi settings external email domains provision --name support.example.com
2

Verify the domain

After adding the required DNS records, verify the domain:
POST /admin/external/email/domains/:id/verify
3

Set up the inbound webhook

POST /admin/external/email/webhooks/provision
This registers the Resend inbound webhook so that email received at your domain triggers the Convex processing pipeline.
To check the current state of your email infrastructure: 
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. 
POST /admin/external/mailboxes
To view existing mailboxes: 
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. 
POST /admin/external/mailboxes/:id/routing-rules
To view routing rules for a mailbox: 
oi settings external mailboxes routing-rules list support@company.com
Routing rules can fan a single inbound address into multiple workflows within the mailbox domain based on sender, subject, or other match criteria.

​
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: 
POST /browse/:key/conversation/send
This sends an email to the conversation participants through the provisioned mailbox address.

​
Viewing a work item’s conversation

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