# Email

Deploy AI agents as email-based conversational interfaces, powered by SendGrid.

***

## Overview

The Email channel enables your agent to receive and respond to emails. Inbound emails arrive via SendGrid's Inbound Parse webhook, are processed by the compiled agent, and responses are sent back through the SendGrid Mail Send API.

## Setup

### Prerequisites

* A SendGrid account with an API key
* A verified sender domain for outbound emails
* Environment variables configured:
  * `SENDGRID_API_KEY` — your SendGrid API key
  * `SENDGRID_FROM_EMAIL` — the default sender email address

### Create a Channel

1. Go to **Deployment** > **Channels**
2. Click **Create Channel** and select **Email**
3. Configure the channel:
   * **From Email** — the sender email address (must be verified in SendGrid)
   * **From Name** — display name for outbound emails
   * **Reply-To Email** — optional reply-to address
   * **Domain Name** — your verified sending domain
4. Save the channel configuration

### Domain Verification

SendGrid requires domain authentication for reliable email delivery:

1. Add DNS records (CNAME) as directed by SendGrid
2. Verify the domain in your SendGrid dashboard
3. Set `domain_verified` to true on the channel

### Bind to a Dispatch

1. Create or edit a dispatch, selecting your compiled agent
2. Add the Email channel to the dispatch
3. Set the dispatch to **ACTIVE**

## How It Works

### Inbound Emails

Inbound emails are received via SendGrid's Inbound Parse:

1. SendGrid receives email at the configured MX record domain
2. The email content is forwarded to the platform ingress endpoint
3. The agent processes the email body with the compiled system prompt
4. A response email is sent via the SendGrid Mail Send API

### Outbound Emails

```
OutboundMessageService.send_email()
      │
      ├─ POST https://api.sendgrid.com/v3/mail/send
      ├─ Authorization: Bearer {SENDGRID_API_KEY}
      ├─ From: configured from_email / from_name
      ├─ To: recipient email
      ├─ Subject: conversation subject line
      └─ Content: HTML body with optional footer
```

* Messages are tracked with SendGrid message IDs
* Open tracking and click tracking are configurable per channel

## Configuration

| Setting                  | Description                                          |
| ------------------------ | ---------------------------------------------------- |
| **Provider**             | `sendgrid` (default)                                 |
| **API Key**              | SendGrid API key (encrypted at rest via AES-256-GCM) |
| **From Email**           | Verified sender email address                        |
| **From Name**            | Display name for the sender                          |
| **Reply-To Email**       | Optional reply-to address                            |
| **Domain Name**          | Verified sending domain                              |
| **Domain Verified**      | Whether domain authentication is complete            |
| **Footer HTML**          | Custom HTML footer appended to all emails            |
| **Templates**            | Email templates for structured responses             |
| **Open Tracking**        | Track email opens (default: enabled)                 |
| **Click Tracking**       | Track link clicks (default: enabled)                 |
| **Unsubscribe Group ID** | SendGrid list management group                       |

## Testing

1. Configure the channel with a verified sender
2. Use the **Preview Test Email** feature to send a test message
3. Send an email to your configured inbound address
4. Monitor the conversation in **Session Monitoring**

## Troubleshooting

| Symptom                      | Possible Cause           | Resolution                                     |
| ---------------------------- | ------------------------ | ---------------------------------------------- |
| Outbound emails not arriving | Domain not verified      | Complete SendGrid domain authentication        |
| Emails landing in spam       | Missing DNS records      | Verify DKIM, SPF, and DMARC records            |
| Inbound emails not processed | MX record not configured | Point MX records to SendGrid inbound parse     |
| API errors on send           | Invalid API key          | Verify `SENDGRID_API_KEY` environment variable |
| Tracking not working         | Tracking disabled        | Check open/click tracking settings on channel  |

## See Also

* [Channel Architecture](https://docs.adaptiveap.com/technical-how-it-works/channel-architecture) — how channels connect to the dispatch system
* [Webhooks](https://docs.adaptiveap.com/deployment/webhooks) — event-driven integrations
* [Security & Data Handling](https://docs.adaptiveap.com/technical-how-it-works/security) — encryption and data handling practices


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.adaptiveap.com/deployment/email.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.