Skip to main content
Connic
Connectors

Email

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

Last updated
On this page
Inbound (IMAP)
Monitor your mailbox for incoming emails and trigger agent runs. Linked agents receive parsed message fields, metadata, and supported attachments.

Setup Instructions

1

Get your IMAP credentials

Server, port, username, and password. For Gmail: enable 2FA and create an App Password.

2

Create the connector

Open your agent, click Add inbound connector, then Create New Connector and select Email.

3

Configure and create

Choose Inbound (IMAP) mode, enter IMAP Server, Port, Username, Password, and optionally a Folder to monitor. Click Create and Connic starts monitoring the mailbox.

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 replies.

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:

  1. Enable 2-factor authentication on your Google account
  2. Go to Security → App passwords
  3. Generate a new app password for "Mail"
  4. 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 parsed email content and metadata:

email-payload.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",
    "uid": "12345",
    "timestamp": "2024-12-30T15:30:05.123Z"
  }
}

Attachments

Supported attachments up to 10 MB are included with their content. The connector 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)
Use this as an automatic outbound connector, agent-tool outbound connector, or middleware outbound connector.

Setup Instructions

1

Get your SMTP credentials

Server, port, username, and password.

2

Create the connector

Open your agent, click Add outbound connector, then Create New Connector and select Email.

3

Configure and create

Choose Outbound (SMTP) mode, enter the SMTP connection and From Address, and optionally set a Default Recipient. Click Create to send completed agent outputs by email.

How Outbound Works

Automatic outbound connectors interpret the completed run's final output as an email. Agent-tool and middleware outbound connectors send only when called. In every mode, Connic builds the MIME message and applies the stored SMTP connection, sender, and retries.

Agent-tool and Middleware Outbound Connectors

An agent-tool outbound connector exposes an editable tool name, defaulting to send_to_<connector_name>. Call a middleware outbound connector by its configured name through send_connector. Both use the payload schema below. body is required; all other fields are optional.

connector-payload.json
{
  "body": "Your request has been resolved.",
  "to": ["customer@example.com"],
  "subject": "Re: Your Support Request",
  "html_body": "<p>Your request has been resolved.</p>",
  "cc": ["manager@example.com"],
  "bcc": ["archive@example.com"],
  "reply_to": "support@example.com"
}

to, cc, and bcc accept one address or an array. The recipient comes from to, then the connector's Default Recipient, then matching inbound email context. Stored addresses and SMTP credentials are not exposed to the model.

Automatic Output
Existing automatic outbound connectors keep the legacy behavior: final JSON sets email fields, while a plain string becomes the body and requires a resolvable recipient. Links without outbound connector settings remain Automatic / All runs.

Structured JSON

Use these fields to control the message. A recipient must come from to, the connector's Default Recipient, or matching inbound email context:

output.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; falls back to Default Recipient, then the matching inbound sender
  • subject: Email subject line; replies reuse the inbound subject with Re:, otherwise it defaults to Agent Response
  • body: Plain-text body; message is also accepted

Optional Fields

Include optional fields for more control:

output.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; html is also accepted
  • reply_to: Reply-to address

Agent Implementation Example

For an automatic outbound connector, a tool can construct the final email JSON and an output schema can validate it. Agent-tool outbound connectors use the connector-owned payload schema instead, so the final response can remain user-facing text.

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

name: email-responder
type: llm
model: connic/gpt-5.6-terra
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
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
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: Server port (default: 587)
  • Username: Your email address
  • Password: Your password or app-specific password
  • From Address: Sender email address
  • From Name: Display name for the sender (optional)
  • Default Recipient: Fallback when output does not include to (optional)
  • Use TLS: Enable SMTP STARTTLS (default: enabled)

Security

  • Optional STARTTLS encryption
  • Credentials encrypted at rest
  • Automatic retries on delivery failures

Example Workflow

Combine inbound and outbound for automated email handling:

  1. Inbound connector receives support email
  2. Agent analyzes the request and determines response
  3. Agent returns email fields as JSON or a plain-text body
  4. Outbound connector sends the AI-generated response

Explore connectors

Connector Modes

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