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.

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

You can provide a single value or set up multiple accounts. Save these values from your email provider:

Parameter	Description	Example
SMTP Server	Outgoing mail server	smtp.gmail.com
SMTP Port	SMTP server port	587 (TLS) or 465 (SSL)
IMAP Server	Incoming mail server	imap.gmail.com
IMAP Port	IMAP server port	993 (SSL)
Username	Full email address	user@example.com
Password	Account or app password	your_app_password

Configuring Flametree Integration

Step 1: Create Email Integration

1. Navigate to Channels

   • Go to Settings > Channels.
   • Open Email (IMAP/SMTP)
   • Select Add +.

2. Fill Configuration

   Field	Description	Required	Example	Value Source
   Name	Custom integration name	✅ Yes	Support Email Connector	Your choice
   Description	Integration purpose	✅ Yes	Customer support email integration	Your choice
   SMTP Server URL	Outgoing mail server (single or multiple)	✅ Yes	smtp.gmail.com	Email provider settings
   SMTP Server Port	SMTP port number (single or multiple)	✅ Yes	587	Email provider settings
   IMAP Server URL	Incoming mail server (single or multiple)	✅ Yes	imap.gmail.com	Email provider settings
   IMAP Server Port	IMAP port number (single or multiple)	✅ Yes	993	Email provider settings
   Email Address	Full email address (single or multiple)	✅ Yes	support@company.com	Your email account
   Password	App-Specific Password (single or multiple)	✅ Yes	your_app_password	Your email account
   Enable OAUTH (true/false)	Enable OAuth authentication	❌ No	true	Your email account
   OAUTH Refresh Token	Long-lived refresh token (single or multiple)	⚠️ OAuth only	refresh_token_here	OAuth provider console
   OAUTH Token URI	Token endpoint URL (single or multiple)	⚠️ OAuth only	https://oauth2.googleapis.com/token	OAuth provider docs
   OAUTH Client ID	Application client ID (single or multiple)	⚠️ OAuth only	client_id_here	OAuth provider console
   OAUTH Client Secret	Application secret (single or multiple)	⚠️ OAuth only	client_secret_here	OAuth provider console
   Interval (in seconds) for checking updates in the INBOX provided	Check interval for new messages	❌ No	15	Your choice
   Interval (in seconds) for checking receipts in the INBOX provided	Check interval for delivery receipts	❌ No	15	Your choice

Example of using multiple values

If a field supports multiple values, separate them with a comma (,).

Example: first@mail.com, second@mail.com

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

Multi-account email behavior

When you connect multiple email accounts to the same channel, Flametree sends outbound emails through these accounts one by one in a fixed repeating sequence (round-robin). You can add as many email accounts as needed, there is no limit.

After a recipient receives their first email, Flametree links that recipient to the specific account that sent it. From that moment on, Flametree always sends emails to this recipient from the same email account. This keeps the sender identity consistent, maintains email thread continuity, and reduces the risk of messages being blocked.

3. 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 Communication 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.

Popular Email Provider Settings

Provider	SMTP Server	SMTP Port	IMAP Server	IMAP Port	Security
Gmail	smtp.gmail.com	587	imap.gmail.com	993	TLS/SSL
Outlook/Office 365	smtp.office365.com	587	outlook.office365.com	993	TLS/SSL
Yahoo	smtp.mail.yahoo.com	587	imap.mail.yahoo.com	993	TLS/SSL
Exchange	mail.company.com	587	mail.company.com	993	TLS/SSL

Configuration Options

Environment Variables

Configure additional features through Set Environment Variables:

Variable	Description	Default
EMAIL_RETRY_LIMIT	Define number of email client request attempts before graceful exit. IMAP/SMTP channel only.	3

To configure:

1. Go to your agent's Set Environment Variables
2. Add the variable name and desired value
3. Save and restart the agent

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

List length mismatch when using multiple accounts

Symptoms: Validation errors or unexpected authentication failures on some accounts.

Solutions:

1. Ensure the number of values in EMAIL_ADDRESS matches EMAIL_PASSWORD (non‑OAuth) or OAUTH_REFRESH_TOKEN (OAuth).
2. If providing lists for servers/ports, make sure their lengths match the number of email addresses.
3. Remove accidental trailing commas or empty values; spaces around commas are ignored.

Mixed authentication modes

Symptoms: Channel fails to start when some accounts use passwords and others use OAuth.

Solutions:

1. Set IS_OAUTH (Enable OAuth) to a single, consistent value for the whole channel.
2. If you need both modes, create separate email channel integrations.

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 (for example, 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.

Can I connect multiple email accounts to a single email channel?

Yes. Enter comma‑separated values for accounts and related credentials. OAuth enablement (IS_OAUTH/Enable OAuth) is a single boolean for the whole channel — either all accounts use OAuth or none. Make sure list lengths match across related fields (addresses ↔ passwords or refresh tokens). Inbound polling will monitor all accounts.

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