Skip to main content
Email Bot enables your AI agents to interact with users through standard email protocols. It handles bidirectional communication using IMAP for polling and SMTP for sending.

​
Quick Start

Enable email communication for your agents with a few lines of code.
1

Set Environment Variables

Configure your email service credentials. For Gmail, use an App Password.
export EMAIL_ADDRESS="your-bot@gmail.com"
export EMAIL_APP_PASSWORD="xxxx xxxx xxxx xxxx"
# Optional: defaults to Gmail
export EMAIL_IMAP_SERVER="imap.gmail.com"
export EMAIL_SMTP_SERVER="smtp.gmail.com"
2

Create and Start Bot

Simple Python implementation using the Bot factory.
from praisonai.bots import Bot
from praisonaiagents import Agent
import asyncio

# Define your agent
agent = Agent(
    name="Professional Assistant",
    instructions="Handle incoming emails professionally and concisely."
)

async def main():
    # Initialize EmailBot via factory
    bot = Bot("email", agent=agent)
    
    # Start polling for emails
    await bot.start()

if __name__ == "__main__":
    asyncio.run(main())

​
Key Features

  • Bidirectional Support: Uses IMAP to poll for new messages and SMTP to send responses.
  • Thread Management: Correlates responses using In-Reply-To and References headers to maintain conversation context.
  • Auto-Reply Prevention: Built-in detection for Auto-Submitted headers and common bot addresses to prevent infinite loops.
  • Command Handling: Supports subject-based commands (e.g., START:, STOP:) alongside natural language.
  • Session Isolation: Each sender gets a dedicated AgentState for personalized interactions.

​
Configuration

​
Environment Variables

VariableDefaultDescription
EMAIL_ADDRESS—The email address of the bot
EMAIL_APP_PASSWORD—Authentication password (App Password recommended)
EMAIL_IMAP_SERVERimap.gmail.comIMAP server for reading emails
EMAIL_IMAP_PORT993IMAP SSL port
EMAIL_SMTP_SERVERsmtp.gmail.comSMTP server for sending emails
EMAIL_SMTP_PORT465SMTP SSL port
EMAIL_POLL_INTERVAL60Seconds between email checks

​
BotConfig Options

from praisonaiagents import BotConfig

config = BotConfig(
    command_prefix="!",           # Prefix for email commands
    typing_indicator=False,       # N/A for email
    reply_in_thread=True,         # Always use reply headers
    allowed_users=["boss@company.com"], # Restricted access
)

​
Deployment Modes

​
CLI Mode

Deploy directly from your agents.yaml file: 
praisonai bot email --agent agents.yaml

​
Script Mode

Full control over headers and attachment handling by extending the EmailBot class.

​
Best Practices

Never use your main account password. Generate a platform-specific App Password for the bot.
Use BotConfig.blocked_users to exclude noreply addresses or known marketing domains.
Tell your users to keep subject lines consistent for better thread correlation.

Messaging Bots

Comparison of all messaging platforms

Bot Commands

Register custom subject-line commands