> ## Documentation Index
> Fetch the complete documentation index at: https://ago.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Send Email Tool

> Send emails from agent conversations

The AGO Send Email Tool enables agents to send emails during conversations using AWS Simple Email Service (SES).

## Overview

**Tool Name:** `ago_send_email`

This tool allows agents to send emails to users, enabling workflows like sending confirmation emails, documentation, follow-up information, or automated notifications.

## Key Features

* HTML and plain text email support
* Template-based emails with variables
* Attachment handling
* Dynamic content with Jinja2 templates
* Integration with AWS SES
* Trigger-based automation support

***

## Prerequisites

### AWS SES Requirements

Before using the Send Email tool, you must:

1. **Create an AWS account** with SES access
2. **Verify sender identity** (email address or domain)
3. **Move out of sandbox** for production use
4. **Create IAM credentials** with SES permissions

### AWS Setup

You need an AWS account with SES (Simple Email Service) configured. Refer to the [AWS SES documentation](https://docs.aws.amazon.com/ses/latest/dg/Welcome.html) for:

* Creating an IAM user with `ses:SendEmail` and `ses:SendRawEmail` permissions
* Verifying a sender identity (domain or email address)
* Moving out of the SES sandbox for production use

***

## AGO Configuration

### Configure via Admin Interface

1. Navigate to **Settings** → **Email Configuration**
2. Enter your AWS credentials:
   * AWS Access Key ID
   * AWS Secret Access Key
   * AWS Region (e.g., `eu-central-1`)
3. Configure email addresses:
   * From Address (must be verified in SES)
   * Reply-To Address (optional)
4. Enable email sending
5. Save changes

### Configuration Fields

| Setting               | Required | Description                               |
| --------------------- | -------- | ----------------------------------------- |
| AWS Access Key ID     | Yes      | IAM access key with SES permissions       |
| AWS Secret Access Key | Yes      | IAM secret key (stored encrypted)         |
| AWS Region            | Yes      | AWS region for SES (e.g., `eu-central-1`) |
| From Address          | Yes      | Verified sender email address             |
| Reply-To Address      | No       | Reply-to email address                    |
| Email Domain          | No       | Domain for email construction             |
| Enable Email          | Yes      | Toggle email sending on or off            |

***

## Tool Configuration

### Create Email Tool for Agent

1. Navigate to **AI Studio** → **Tools**
2. Click **Create Tool**
3. Select **Send Email** as the tool type
4. Configure the tool settings:
   * **Name**: Internal identifier (e.g., "send\_customer\_email")
   * **Display Name**: User-facing name (e.g., "Send Email")
   * **Description**: What the tool does
   * **Prompt**: When the agent should use this tool
5. Define the **Input Schema** with required fields:
   * `to_email`: Email address to send to
   * `subject`: Email subject line
   * `body`: Email body content (HTML supported)
6. Click **Save**

### Assign to Agent

1. Navigate to **AI Studio** → **Agents**
2. Select the agent you want to configure
3. Go to the **Tools** tab
4. Add the Send Email tool to the agent's tool list
5. Click **Save**

***

## Input Schema

### Standard Fields

| Field      | Type   | Required | Description                                      |
| ---------- | ------ | -------- | ------------------------------------------------ |
| to\_email  | string | Yes      | Recipient email address                          |
| subject    | string | Yes      | Email subject line                               |
| body       | string | Yes      | Email body (HTML or plain text)                  |
| html\_body | string | No       | HTML version of the email body                   |
| cc         | string | No       | CC recipients (comma-separated email addresses)  |
| bcc        | string | No       | BCC recipients (comma-separated email addresses) |

### Extended Schema Example

For more complex email workflows, add additional input fields:

| Field           | Type | Description                                             |
| --------------- | ---- | ------------------------------------------------------- |
| to\_email       | str  | Customer email address                                  |
| recipient\_name | str  | Customer name for personalization                       |
| subject         | str  | Email subject                                           |
| body            | str  | Email body content                                      |
| email\_type     | enum | Type of email (confirmation, follow\_up, documentation) |

***

## Email Templates

### HTML Template Example

```html theme={null}
<!DOCTYPE html>
<html>
<head>
  <style>
    .container { max-width: 600px; margin: 0 auto; font-family: Arial, sans-serif; }
    .header { background: #0069ED; color: white; padding: 20px; text-align: center; }
    .content { padding: 20px; background: #f9f9f9; }
    .footer { padding: 15px; text-align: center; font-size: 12px; color: #666; }
    .button { background: #0069ED; color: white; padding: 12px 24px; text-decoration: none; border-radius: 4px; }
  </style>
</head>
<body>
  <div class="container">
    <div class="header">
      <h1>{{ company_name }}</h1>
    </div>
    <div class="content">
      <p>Hello {{ recipient_name }},</p>
      <p>{{ message_content }}</p>
      <p><a href="{{ action_url }}" class="button">{{ action_text }}</a></p>
    </div>
    <div class="footer">
      <p>{{ company_name }} | {{ company_address }}</p>
      <p><a href="{{ unsubscribe_url }}">Unsubscribe</a></p>
    </div>
  </div>
</body>
</html>
```

### Template Variables

| Variable                 | Source                | Description        |
| ------------------------ | --------------------- | ------------------ |
| `{​{ recipient_name }}`  | User profile or input | Recipient's name   |
| `{​{ recipient_email }}` | User profile or input | Recipient's email  |
| `{​{ company_name }}`    | Configuration         | Your company name  |
| `{​{ message_content }}` | Tool input            | Dynamic content    |
| `{​{ sender_name }}`     | Agent                 | Sending agent name |
| `{​{ conversation_id }}` | Thread                | Reference number   |

***

## Usage in Conversations

### Example Flow

```
User: Can you send me the installation guide?

Agent: I'll send that to you right away. What email address
       should I send it to?

User: john@example.com

Agent: [Calls send_email tool with:
        - to_email: john@example.com
        - subject: "Your Installation Guide"
        - body: "<p>Here's the installation guide you requested...</p>"]

Agent: Done! I've sent the installation guide to john@example.com.
       Please check your inbox (and spam folder if you don't see it).
```

### Best Practices for Agents

Include in the agent's prompt:

```markdown theme={null}
## Email Tool Usage

When sending emails:
1. Always confirm the email address before sending
2. Provide a clear subject line
3. Include relevant information in the body
4. Inform the user that the email was sent
5. Suggest checking spam folder if not received

Do NOT:
- Send unsolicited emails
- Include sensitive information without user consent
- Send multiple emails for the same request
```

***

## Trigger-Based Emails

Send automated emails based on events using triggers.

### Creating Email Triggers

1. Navigate to the **Triggers** configuration
2. Click **Create Trigger**
3. Select a trigger event (e.g., "Ticket Created")
4. Add a **Send Email** action
5. Configure the email:
   * **To**: Use template variables like `{{ user.email }}`
   * **Subject**: Include dynamic data like `Your support ticket #{{ ticket.id }} has been created`
   * **Template**: Select an email template
6. Enable the trigger and click **Save**

### Available Trigger Events

| Event                            | Use Case                   |
| -------------------------------- | -------------------------- |
| `ticket_created`                 | Confirmation email to user |
| `ticket_status_changed`          | Status update notification |
| `thread_completed`               | Follow-up survey email     |
| `satisfaction_feedback_received` | Thank you email            |

***

## Deliverability Best Practices

### DNS Configuration

Configure these records for better deliverability:

| Record    | Purpose                                     |
| --------- | ------------------------------------------- |
| **SPF**   | Authorize SES to send on your behalf        |
| **DKIM**  | Email authentication signatures             |
| **DMARC** | Policy for handling authentication failures |

### SPF Record Example

```
v=spf1 include:amazonses.com ~all
```

### Content Guidelines

* **Clear subject lines**: Be specific about email purpose
* **Professional formatting**: Use consistent branding
* **Mobile-friendly**: Design for mobile viewing
* **Unsubscribe option**: Include for marketing emails
* **Avoid spam triggers**: No excessive caps, punctuation, or spam words

***

## Troubleshooting

<AccordionGroup>
  <Accordion title="Issue: Emails not sending">
    **Problem**: Tool executes but email never arrives.

    **Solutions:**

    1. Verify email sending is enabled in configuration
    2. Check AWS credentials are correct
    3. Verify sender address is verified in SES
    4. Check SES sending statistics for errors
    5. Review AWS CloudWatch logs
  </Accordion>

  <Accordion title="Issue: Emails going to spam">
    **Problem**: Emails arrive in spam folder.

    **Solutions:**

    1. Configure SPF record for your domain
    2. Set up DKIM signing in SES
    3. Consider DMARC policy
    4. Use consistent "From" address
    5. Avoid spam trigger words
  </Accordion>

  <Accordion title="Issue: SES sandbox limitations">
    **Problem**: Can only send to verified addresses.

    **Solutions:**

    1. Request production access from AWS
    2. Verify recipient addresses for testing
    3. Use SES simulator for development
  </Accordion>

  <Accordion title="Issue: Rate limit errors">
    **Problem**: Receiving throttling errors from SES.

    **Solutions:**

    1. Request sending limit increase from AWS
    2. Implement exponential backoff
    3. Queue emails for batch sending
    4. Monitor sending rate
  </Accordion>

  <Accordion title="Issue: AWS credential errors">
    **Problem**: Authentication failures with SES.

    **Solutions:**

    1. Verify access key and secret
    2. Check IAM permissions
    3. Ensure region matches SES setup
    4. Regenerate credentials if needed

    ***
  </Accordion>
</AccordionGroup>

## API Reference

### Test Email Configuration

To test your email configuration, use the **Test Email** button in **Settings** → **Email Configuration**.

For programmatic access, see:

* [Public API v1 Reference](../api/public-api-v1) - Tool management and configuration

***

## Related Documentation

* [Tools Description Guide](../guides/tools-description) - Best practices for tool descriptions
* [Tools Overview](../features/tools) - Tool configuration
* [Ticket Triggers](../features/triggers-feature) - Event-based automation
* [Agents](../agent/agents) - Agent configuration