Personal Email

Connect your personal email account (Gmail, Outlook, Yahoo, or custom IMAP/SMTP) to allow agents to send and receive emails on your behalf.

Prerequisites

To connect a personal email account, you need:

IMAP/SMTP Access: Your email provider must support IMAP and SMTP protocols.
App Password: Most providers (like Gmail and Outlook) require an “App Password” instead of your regular login password if 2FA is enabled.
- Gmail: Sign in with App Passwords
- Outlook: Manage app passwords

Configuration

Configuring a personal email involves two steps: saving the public configuration (host, port, user) in the site settings and securely storing the password.

Step 1: Store Secure Credentials

First, you must securely store the email password or App Password.

Endpoint: POST /api/secure-tokens/encrypt


{
  "site_id": "your-site-uuid",
  "token_type": "email",
  "identifier": "user@example.com",
  "value": "your-app-password",
  "store_in_db": true
}

Step 2: Update Site Settings

Next, update the site settings with the connection details.

Endpoint: PATCH /api/sites/{site_id}/settings


{
  "channels": {
    "email": {
      "email": "user@example.com",
      "incomingServer": "imap.gmail.com",
      "incomingPort": 993,
      "outgoingServer": "smtp.gmail.com",
      "outgoingPort": 587,
      "aliases": ["support@example.com"]
    }
  }
}

email: The email address used for login.
incomingServer: IMAP host (e.g., imap.gmail.com).
incomingPort: IMAP port (usually 993 for SSL).
outgoingServer: SMTP host (e.g., smtp.gmail.com).
outgoingPort: SMTP port (usually 587 for TLS or 465 for SSL).
aliases: Optional list of alias email addresses.

Step 3: Verify Connection

You can verify the configuration using the check endpoint.

Endpoint: POST /api/agents/email/check


{
  "site_id": "your-site-uuid",
  "use_saved_credentials": true
}

This will attempt to connect to both IMAP and SMTP servers using the stored credentials.

Usage

Sending Emails

Once configured, agents can send emails using the standard tool.

Endpoint: POST /api/agents/tools/sendEmail


{
  "site_id": "your-site-uuid",
  "to": "customer@example.com",
  "subject": "Hello",
  "content": "Message body..."
}

Receiving Emails

The system automatically monitors the inbox (via IMAP) for new messages and processes them according to the agent’s logic.