Skip to main content

How to connect Email to an AI Agent

Connect your Flametree AI agent to email systems using IMAP/SMTP protocols to enable automated communication through email channels. This integration supports both traditional email providers and Microsoft Exchange environments.

Prerequisites​

  • Email Account with IMAP/SMTP access enabled
  • SMTP server credentials for sending emails
  • IMAP server credentials for receiving emails
  • 2-Factor Authentication (2FA) enabled on your email account
  • App password or OAuth credentials (strongly recommended)
  • Admin access to your Flametree account

Setting Up Email Integration​

Step 1: Prepare Email Account​

  1. Enable IMAP/SMTP Access

    • For Gmail: Enable "Less secure app access" or use App Passwords
    • For Outlook: Ensure IMAP is enabled in account settings
    • For corporate emails: Contact IT admin for server details

  2. Generate App-Specific Password

    • Gmail: Google Account → Security → 2-Step Verification → App passwords
    • Outlook: Account Security → Additional security options → App passwords
    • Yahoo: Account Security → Generate and manage app passwords

Step 2: Collect Email Server Information​

Save these values from your email provider:

ParameterDescriptionExample
SMTP ServerOutgoing mail serversmtp.gmail.com
SMTP PortSMTP server port587 (TLS) or 465 (SSL)
IMAP ServerIncoming mail serverimap.gmail.com
IMAP PortIMAP server port993 (SSL)
UsernameFull email addressuser@example.com
PasswordAccount or app passwordyour_app_password

Configuring Flametree Integration​

Step 1: Create Email Integration​

  1. Navigate to Integrations
    • Go to Channels section in Flametree
    • Find IMAP/SMTP card and click Add +

💡 Note: IMAP/SMTP integration from Integrations section is outdated. Use Channels instead.

  1. Fill Configuration

    FieldDescriptionRequiredExampleValue Source
    NameCustom integration name✅ YesSupport Email ConnectorYour choice
    DescriptionIntegration purpose✅ YesCustomer support email integrationYour choice
    SMTP Server URLOutgoing mail server✅ Yessmtp.gmail.comEmail provider settings
    SMTP Server PortSMTP port number✅ Yes587Email provider settings
    IMAP Server URLIncoming mail server✅ Yesimap.gmail.comEmail provider settings
    IMAP Server PortIMAP port number✅ Yes993Email provider settings
    User nameFull email address✅ Yessupport@company.comYour email account
    PasswordApp-Specific Password✅ Yesyour_app_passwordYour email account
    Interval (in seconds) for checking updates in the INBOX providedCheck interval for new messages❌ No15Your choice
    Interval (in seconds) for checking receipts in the INBOX providedCheck interval for delivery receipts❌ No15Your choice
    Enable OAUTH (true/false)Enable OAuth authentication❌ NotrueYour email account
    OAUTH Refresh TokenLong-lived refresh token⚠️ OAuth onlyrefresh_token_hereOAuth provider console
    OAUTH Token URIToken endpoint URL⚠️ OAuth onlyhttps://oauth2.googleapis.com/tokenOAuth provider docs
    OAUTH Client IDApplication client ID⚠️ OAuth onlyclient_id_hereOAuth provider console
    OAUTH Client SecretApplication secret⚠️ OAuth onlyclient_secret_hereOAuth provider console

    Standard Ports:

    • SMTP: 587 (TLS), 465 (SSL), 25 (unencrypted)
    • IMAP: 993 (SSL), 143 (unencrypted)

    Recommended intervals:

    • 15 seconds — Critical support channels
    • 60 seconds — Standard business email
    • 300 seconds — Low-priority or bulk email

  2. Save Integration

    • Click Save to create the integration

Step 2: Connect to AI Agent​

  1. Open Agent Configuration

    • Navigate to your target AI agent's settings
    • Go to Channels section

  2. Assign Channel

    • Select your email integration from the list
    • Save the agent configuration

  3. Restart Agent

    • Restart the agent for changes to take effect
    • This step is mandatory for the integration to work

❗️ Important: Always restart both the agent and channel after making changes.

ProviderSMTP ServerSMTP PortIMAP ServerIMAP PortSecurity
Gmailsmtp.gmail.com587imap.gmail.com993TLS/SSL
Outlook/Office 365smtp.office365.com587outlook.office365.com993TLS/SSL
Yahoosmtp.mail.yahoo.com587imap.mail.yahoo.com993TLS/SSL
Exchangemail.company.com587mail.company.com993TLS/SSL

Common Issues & Solutions​

Authentication failures

Possible causes:

  • Incorrect username/password
  • 2FA enabled without app password
  • IMAP/SMTP disabled on account

Solutions:

  1. Verify credentials: Double-check username and password
  2. Generate app password: Create app-specific password for 2FA accounts
  3. Enable IMAP/SMTP: Check provider settings to ensure protocols are enabled
  4. Check account status: Verify account is not locked or suspended
Connection timeouts

Possible causes:

  • Incorrect server settings
  • Firewall blocking connections
  • Server overload

Solutions:

  1. Verify server details: Check SMTP/IMAP server URLs and ports
  2. Test connectivity: Use telnet to test server connectivity
  3. Check firewall: Ensure outbound connections are allowed
  4. Try different ports: Test alternative ports (587 vs 465 for SMTP)
Messages not being sent

Possible causes:

  • SMTP configuration errors
  • Rate limiting
  • Email blocked by provider

Solutions:

  1. Check SMTP settings: Verify server, port, and authentication
  2. Review rate limits: Check provider's sending limits
  3. Test with different recipient: Rule out recipient-specific issues
  4. Check spam folders: Verify messages aren't being filtered
Messages not being received

Possible causes:

  • IMAP configuration errors
  • Folder permissions
  • Agent not restarted

Solutions:

  1. Verify IMAP settings: Check server, port, and authentication
  2. Check folder access: Ensure IMAP has access to INBOX
  3. Restart agent: Restart your Flametree agent after configuration
  4. Review polling interval: Ensure reasonable update interval

FAQ​

Do I need a dedicated email account for the AI agent?

Recommended: Yes, use a dedicated email account (e.g., support@company.com) to avoid conflicts with personal or other business emails. This provides better organization and security.

Can I use the same email account for multiple agents?

It depends on the channel mode:

  • ✅ Yes — If you're using the channel for outbound communications only
  • ❌ No — If any agent has inbound mode enabled for this channel

Why this limitation exists:

  • Multiple agents listening for inbound emails would cause conflicts
  • Messages might be processed by multiple agents simultaneously
  • Response duplication and inconsistent behavior would occur

Best practice: Use dedicated email accounts for each agent to ensure reliable message handling and avoid conflicts.

What's the difference between IMAP and POP3?
  • IMAP: Syncs with server, messages stay on server, supports multiple clients
  • POP3: Downloads messages locally, removes from server, single client access

Flametree uses IMAP for better integration and message management.

How do I set up OAuth instead of password authentication?

OAuth provides enhanced security but requires additional setup:

  1. Create OAuth app in your email provider's developer console
  2. Configure redirect URIs and scopes
  3. Generate refresh token using authorization code flow
  4. Enter OAuth credentials in Flametree integration

See provider-specific documentation for detailed OAuth setup steps.

What email features are supported?

Flametree email integration supports:

  • ✅ Text emails (HTML and plain text)
  • ✅ File attachments
  • ❌ Multiple recipients (To, CC, BCC)
How to configure a calendar?

Default behavior: If no custom calendar is connected, the agent automatically offers 3 fixed time slots for the next day using internal logic.

For real calendar integration:

  1. Create custom skill group with calendar API skills (checkAvailableSlots, createCalendarEvent, cancelCalendarEvent)
  2. Add necessary tools defined in YAML plugin files
  3. Connect skill group to your AI agent via workflow or default_skill_group

This enables the agent to work with actual availability and manage bookings when responding to emails.

Security Considerations​

Credential Security​

  • Use app passwords instead of main account passwords
  • Enable 2FA on email accounts
  • Rotate credentials regularly
  • Use environment variables for sensitive configuration
  • Monitor access logs for unusual activity

Email Security​

  • TLS/SSL encryption for all connections
  • Validate sender identity before processing