---
title: "Email Integration"
source: "https://docs.vertesiahq.com/agent-runner/email-integration"
markdown: "https://docs.vertesiahq.com/llms/agent-runner/email-integration.md"
---

# Email Integration

Vertesia agents support bidirectional email communication, enabling users to interact with agents through their email client. This guide covers the three main email interaction patterns.

## Overview

Email integration enables three distinct interaction patterns:

| Pattern | Trigger | Description |
|---------|---------|-------------|
| **Email-started workflow** | User sends email to agent | User initiates a new agent session by sending an email to a project address |
| **Agent response email** | Agent completes or waits for input | Agent sends results or questions via email; user can reply to continue |
| **Ask user via email** | Agent uses `ask_user` tool | Agent asks questions via email when the user channel is set to email |

All three patterns use a reply-to address format that routes responses back to the correct workflow run.

## Prerequisites

Email integration is configured in **Project Settings > Integrations > Resend Email**.

### Required Settings

| Setting | Description |
|---------|-------------|
| `API Key` | Your [Resend](https://resend.com) API key for sending emails |
| `Inbound Domain` | Domain for sending/receiving email (e.g., `mail.yourcompany.com`) |
| `Webhook Secret` | Resend webhook signing secret for verifying inbound emails |

### Security Settings (Optional)

| Setting | Default | Description |
|---------|---------|-------------|
| `Require Project Access` | Enabled | Only users with project access can start agents via email |
| `Require Email Authentication` | Enabled | Inbound emails must pass DKIM/SPF authentication |
| `Allowed Sender Domains` | Empty (all) | Whitelist of allowed sender email domains |

### DNS Configuration

Your inbound domain requires:

1. **MX records** pointing to Resend's inbound servers
2. **SPF and DKIM records** for email authentication
3. **Webhook configuration** in Resend pointing to `https://your-studio-url/webhooks/resend`

## Pattern 1: Email-Started Workflows

Users can start new agent sessions by sending an email to a project-specific address. This enables email-first workflows where users never need to access another UI.

### Email Address Format

```
{namespace}+{interaction-name}@{inbound_domain}
```

For example:
- `acme+review-contract@mail.vertesia.io` - Start the `review-contract` agent in the `acme` project
- `myproject+analyst@mail.vertesia.io` - Start the `analyst` agent in the `myproject` project

### Access Control

When a user sends an email to start a workflow, the following checks are performed:

1. **Email authentication** (if enabled): DKIM and SPF are verified
2. **Sender domain whitelist**: If `Allowed Sender Domains` is configured, the sender must match
3. **Project access** (if enabled): The sender's email must belong to a user with access to the project
4. **Interaction access**: The interaction must exist and be configured as an agent

### Interaction Data Fields

When a workflow starts via email, the interaction receives the following data fields that can be used in the prompt template:

| Field | Type | Description |
|-------|------|-------------|
| `${message}` | string | The email body (plain text preferred, falls back to HTML) |
| `${email.from}` | string | Sender email address |
| `${email.subject}` | string | Email subject line |
| `${email.source}` | string | Always `"email"` |
| `${email.message_id}` | string | Unique email message ID |
| `${email.has_attachments}` | boolean | Whether the email has attachments |
| `${attachments}` | array | Uploaded attachment metadata (populated async) |

**Example interaction prompt:**

```
# Email Task

## Persona
You are an assistant that processes requests received via email.

## Email Content
**Email from:** ${email.from}
**Subject:** ${email.subject}

**Request:**
${message}

## Task
- Please analyze this request and respond appropriately.
```

### How It Works

1. User sends email to `{namespace}+{agent}@{domain}`
2. Resend webhook receives the email and sends it to Vertesia
3. System verifies sender access and email authentication (based on configuration)
4. A new workflow starts with:
   - Initial message from email body
   - Email channel automatically configured in `user_channels` (with sender's email as `to_email` and thread info)
   - Email metadata (subject, from, attachments) available to the agent
5. Agent processes the request and can use `ask_user` to ask follow-up questions via email
6. User receives responses in their email client and can reply to continue
7. **When the workflow completes, the final result is automatically sent to the user via email**

### Attachments

Email attachments are automatically:
1. Downloaded from Resend
2. Uploaded to the workflow's artifact storage
3. Made available to the agent for processing

## Pattern 2: Agent Response Emails

When a workflow has an email channel configured in `user_channels`, the agent automatically sends emails to the user:

- **Completion emails**: When a non-interactive workflow finishes
- **Response emails**: When an interactive workflow produces output and waits for input
- **Ask user emails**: When the agent needs to ask questions

### How It Works

1. Workflow runs with email channel in `user_channels` (automatic for email-started workflows)
2. Agent processes the request and produces output
3. System sends email with results and a reply-to address: `r+{routeKey}@{inbound_domain}`
4. When user replies, the email is received by the inbound domain
5. Resend sends a webhook to Vertesia
6. The webhook extracts the run ID and sends a `UserInput` signal to the workflow
7. The workflow continues with the user's reply as input

### Email Threading

All emails in a conversation maintain proper threading:
- Subject line preserves `Re: Original Subject`
- `In-Reply-To` and `References` headers enable proper threading in email clients
- Users see all messages in a single thread

## Pattern 3: Ask User via Email

When the workflow has an email channel configured in `user_channels`, the `ask_user` tool sends questions via email in addition to displaying them in the UI.

### Configuration

Configure `user_channels` when starting the agent run, either via the [Agent Runs API](/api/agents) or as workflow variables:

```typescript
const run = await client.store.agents.start({
    interaction: "my-agent",
    interactive: true,
    user_channels: [
        {
            type: "email",
            to_email: "user@example.com"
        }
    ]
});
```

Or equivalently as workflow variables (for scheduled or rule-triggered workflows):

```json
{
    "vars": {
        "interaction": "my-agent",
        "user_channels": [
            {
                "type": "email",
                "to_email": "user@example.com"
            }
        ]
    }
}
```

The email channel supports email threading with optional fields:
- `thread_subject`: Subject for the email thread (without "Re:" prefix)
- `in_reply_to`: Message ID for the In-Reply-To header
- `references`: Array of message IDs for the References header

### How It Works

1. Agent calls `ask_user` with questions
2. System detects email channel in `user_channels` and sends an email to the configured recipient
3. The email contains the questions with context from the conversation
4. User replies to the email with their answers
5. Reply is routed back to the workflow and the agent continues

### Email Formulation

When sending ask_user questions via email, the system uses an LLM to formulate a well-contextualized email that includes:

- Recent conversation context
- The current task being worked on
- The questions being asked
- Instructions for replying

## Automatic Completion Email

When an email channel is configured in `user_channels` (automatically set for email-started workflows), the system will automatically send the workflow result to the user via email when the workflow completes. This ensures users who interact via email always receive their results without needing UI access.

The completion email:
- Includes the full workflow output
- Maintains email threading if part of an existing conversation
- Uses the same reply-to address format, allowing users to continue the conversation

## Reply Address Format

All email flows use a consistent reply-to address format:

```
r+{routeKey}@{inbound_domain}
```

Where `runId` is the Temporal workflow run ID with dashes removed (to comply with RFC 5321's 64-character local-part limit).

When a reply is received:
1. The run ID is extracted from the address
2. Temporal is queried to find the workflow
3. Project and account IDs are retrieved from search attributes
4. The Resend integration settings are used for webhook verification
5. The email content is sent as a `UserInput` signal to the workflow

## Best Practices

### For Email-Started Workflows

- Modify the example prompt to specialize agents
- Handle email attachments appropriately in your agent logic
- Consider user/agent access to content and tools
- Consider all security recommendations

### Security Recommendations

- **Keep `Require Email Authentication` enabled** to prevent email spoofing
- **Keep `Require Project Access` enabled** unless you specifically need public access
- Use `Allowed Sender Domains` to restrict access to specific organizations
- Regularly rotate your Resend API key and webhook secret

## Troubleshooting

### Emails Not Being Received

1. Verify MX records are correctly configured
2. Check Resend webhook is active and pointing to the correct URL
3. Verify `Webhook Secret` matches between Resend and your Vertesia configuration

### Replies Not Reaching Workflow

1. Check the workflow is still running (not completed or timed out)
2. Verify the reply-to address format is correct
3. Check Resend webhook logs for delivery status

### Email-Started Workflows Failing

1. If `Require Project Access` is enabled, verify the sender has project access in Vertesia
2. If `Require Email Authentication` is enabled, check DKIM/SPF authentication is passing
3. Verify the interaction exists and is configured as an agent
4. Check the Resend integration is enabled in Project Settings > Integrations