Connectors

Email (SMTP/IMAP)

Connect your agents to email for intelligent automation. Receive emails to trigger agents (IMAP) or send AI-generated responses (SMTP). Perfect for support automation, email processing, and smart notifications.

Inbound (IMAP)

Monitor your mailbox for incoming emails and trigger agent runs. Each email is processed by all linked agents, with full message content and metadata preserved.

How Inbound Works

Inbound Email connectors connect to your mailbox via IMAP and poll for new messages. When an email arrives, it's parsed and dispatched to all linked agents. Best for support ticket processing, email-to-action workflows, and automated email responses.

Configuration

IMAP Host: Your mail server (e.g., imap.gmail.com)
IMAP Port: Usually 993 for SSL, 143 for plain
Username: Your email address
Password: Your password or app-specific password
Mailbox: Folder to monitor (default: INBOX)

Gmail Configuration

For Gmail, you'll need to use an App Password instead of your regular password:

Enable 2-factor authentication on your Google account
Go to Security → App passwords
Generate a new app password for "Mail"
Use this 16-character password in the connector

Email Filters

Configure filters to process only specific emails:

Unread Only: Only process new/unread emails
Filter by Sender: Only process emails from specific addresses or domains
Filter by Subject: Only process emails containing specific text in subject
Mark as Read: Automatically mark processed emails as read

Agent Payload

The agent receives the full email content and metadata:

json

{
  "from": "John Doe <john@example.com>",
  "from_address": "john@example.com",
  "to": "support@yourcompany.com",
  "subject": "Help with my order #12345",
  "date": "Mon, 30 Dec 2024 10:30:00 -0500",
  "message_id": "<abc123@mail.example.com>",
  "body_text": "Hi, I need help with my recent order...",
  "body_html": "<html><body>Hi, I need help with...</body></html>",
  "attachments": [
    {
      "filename": "receipt.pdf",
      "content_type": "application/pdf",
      "size_bytes": 45678,
      "content": "JVBERi0xLjQKJeLjz9...",
      "encoding": "base64"
    },
    {
      "filename": "notes.txt",
      "content_type": "text/plain",
      "size_bytes": 256,
      "content": "Order notes: Customer requested...",
      "encoding": "text"
    }
  ],
  "_email": {
    "connector_id": "uuid-here",
    "mailbox": "INBOX",
    "timestamp": "2024-12-30T15:30:05.123Z"
  }
}

Attachments

Processable attachments are included with their full content. The connector automatically filters out junk like tracking pixels, favicons, and inline signature images.

Included Attachment Types

Images: JPEG, PNG, GIF, WebP, BMP, TIFF (for vision-capable agents)
Documents: PDF, TXT, CSV, Markdown, JSON, XML, HTML
Office: Word (.docx), Excel (.xlsx), PowerPoint (.pptx)

Filtered Out (Junk)

Tracking pixels and 1x1 spacer images
Favicons and small inline images (<1KB)
Email signature logos and decorations
Unknown/unprocessable file types

Content Encoding

Text files: Included as plain text ("encoding": "text")
Binary files: Base64 encoded ("encoding": "base64")

Note: Attachments larger than 10MB include metadata only (no content) to keep payloads manageable.

Outbound (SMTP)

Send emails when agents complete their runs. The agent response must follow a specific JSON format with recipient, subject, and body fields.

How Outbound Works

Outbound Email connectors connect to your SMTP server. When linked agents complete runs, the connector sends emails based on the agent's output. Best for automated responses, notifications, and report delivery.

Required JSON Format

Your agent must return a JSON object with the email details. The connector will parse this to send the email.

Required Fields

The agent response must include these fields:

json

{
  "to": "customer@example.com",
  "subject": "Re: Your Support Request",
  "body": "Thank you for contacting us. Your issue has been resolved..."
}

to: Recipient email address (required)
subject: Email subject line (required)
body: Plain text email body (required)

Optional Fields

You can also include optional fields for more control:

json

{
  "to": "customer@example.com",
  "cc": "manager@yourcompany.com",
  "bcc": "archive@yourcompany.com",
  "subject": "Your Weekly Report",
  "body": "Here is your weekly summary...",
  "html_body": "<html><body><h2>Weekly Report</h2>...</body></html>",
  "reply_to": "noreply@yourcompany.com"
}

cc: Carbon copy recipients
bcc: Blind carbon copy recipients
html_body: HTML version of the email
reply_to: Reply-to address

Agent Implementation Example

Use a tool to construct the email JSON and optionally enforce an output schema:

yaml

# agents/email-responder.yaml
version: "1.0"

name: email-responder
type: llm
model: gemini/gemini-2.5-flash
description: "Send notifications after task completion"
system_prompt: |
  When a task completes, draft a customer email.
  Use email.compose_notification to build the JSON payload.

tools:
  - email.compose_notification
output_schema: email-response.json

python

# tools/email.py
from typing import Dict, Optional

def compose_notification(
    to: str,
    subject: str,
    body: str,
    html_body: Optional[str] = None,
    cc: Optional[str] = None,
    bcc: Optional[str] = None,
    reply_to: Optional[str] = None,
) -> Dict[str, str]:
    """Build the payload expected by the SMTP connector."""
    payload = {"to": to, "subject": subject, "body": body}
    if html_body:
        payload["html_body"] = html_body
    if cc:
        payload["cc"] = cc
    if bcc:
        payload["bcc"] = bcc
    if reply_to:
        payload["reply_to"] = reply_to
    return payload

json

# schemas/email-response.json
{
  "type": "object",
  "required": ["to", "subject", "body"],
  "properties": {
    "to": { "type": "string" },
    "subject": { "type": "string" },
    "body": { "type": "string" },
    "cc": { "type": "string" },
    "bcc": { "type": "string" },
    "html_body": { "type": "string" },
    "reply_to": { "type": "string" }
  }
}

SMTP Configuration

SMTP Host: Your mail server (e.g., smtp.gmail.com)
SMTP Port: 587 for TLS (recommended), 465 for SSL, 25 for plain
Username: Your email address
Password: Your password or app-specific password
From Address: Sender email address
From Name: Display name for the sender (optional)

Security

TLS encryption for secure transmission
Credentials encrypted at rest
Automatic retry on transient failures

Example Workflow

Combine inbound and outbound for automated email handling:

Inbound connector receives support email
Agent analyzes the request and determines response
Agent returns JSON with to, subject, body
Outbound connector sends the AI-generated response

Connectors Overview

Learn about connector modes

HTTP Webhooks

Trigger agents via HTTP requests

Cron Scheduler

Run agents on a schedule

Output Schema

Structure agent responses as JSON