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
Username	Full email address	user@example.com
Password	Account or app password	your_app_password
IMAP Server	Incoming mail server	imap.gmail.com
IMAP Port	IMAP server port	993 (SSL)
SMTP Server	Outgoing mail server	smtp.gmail.com
SMTP Port	SMTP server port	587 (TLS) or 465 (SSL)

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
Address	One or more email addresses *	✅ Yes	support@company.com	Your email account
Password	Password(s) for address(es) *	✅ Yes	your_app_password	Your email account
IMAP Server	One or more IMAP servers *	✅ Yes	imap.gmail.com	Email provider settings
IMAP Port	IMAP port number *	✅ Yes	993	Email provider settings
SMTP server	One or more SMTP servers *	✅ Yes	smtp.gmail.com	Email provider settings
SMTP Port	SMTP port number *	✅ Yes	587	Email provider settings
Enable OAUTH	Enable OAuth authentication	❌ No	false	Your email account
OAUTH refresh token	One or more refresh tokens *	⚠️ OAuth only	refresh_token_here	OAuth provider console
OAUTH token URI	One or more URI tokens *	⚠️ OAuth only	https://oauth2.googleapis.com/token	OAuth provider docs
OAUTH client ID	One or more client IDs *	⚠️ OAuth only	client_id_here	OAuth provider console
OAUTH client secret	One or more client secrets *	⚠️ OAuth only	client_secret_here	OAuth provider console
Inbox check interval [env CHECK_INTERVAL]	Interval (in seconds) for checking updates in the INBOX provided	❌ No	15	Your choice

* Field can accept multiple values

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 email settings through Set Environment Variables.

Additional Account-Specific Variables (can be single values or comma-separated for multiple accounts):

Variable	Description	Default
EMAIL_NAME	Display From name for the email account(s)	None
IMAP_MAILBOX	IMAP mailbox to monitor	INBOX
SMTP_ATTEMPTS	Number of SMTP send attempts	5
SMTP_DELAY	Delay between SMTP attempts (seconds)	5
FULL_EMAIL_ADDRESS	Full email address with display name. Has a higher priority than EMAIL_NAME	None
FROM_TEMPLATE	Template for sender display format	{} <{}>
MESSAGE_CONTENT_TYPE	Email content type	text/plain

Channel-Level Variables:

Variable	Description	Default
EMAIL_RETRY_LIMIT	Number of email client request attempts before graceful exit	3
EMAIL_MAX_ATTACHMENT_BYTES	Maximum size of inbound attachments (bytes). Set to 0 to disable limiting	10485760 (10 MB)

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