Email Integration

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

Overview

Email integration enables three distinct interaction patterns:

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

Security Settings (Optional)

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: 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 2: 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 with an email channel in your workflow variables:

{
    "vars": {
        "type": "conversation",
        "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

Pattern 3: 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 the Studio 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:

Example interaction prompt:

You are an assistant that processes requests received via email.

**Email from:** {{email.from}}
**Subject:** {{email.subject}}

**Request:**
{{message}}

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

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 Ask User via Email

• Configure the LLM environment and model for email formulation
• Keep questions concise and numbered for easy reference
• Provide sufficient context for users to answer without accessing the UI

For Email-Started Workflows

• Document the email address format for users
• Consider setting up Allowed Sender Domains for security
• Design agents to be self-contained (don't assume UI access)
• Handle email attachments appropriately in your agent logic

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