Skip to main content
Give your agents email superpowers. Just set env vars — tools auto-detect the right backend. 
from praisonaiagents import Agent
from praisonai_tools import EmailTool

agent = Agent(name="InboxAssistant", tools=[EmailTool()])
agent.start("Check my inbox for unread messages from Bob")
The user asks about mail; the agent reads or sends email through the configured inbox tool.

​
Quick Start

1

Simple Usage

from praisonaiagents import Agent
from praisonaiagents.tools.email_tools import send_email, list_emails, search_emails, archive_email

agent = Agent(
    name="EmailAgent",
    instructions="You help send and manage emails.",
    tools=[send_email, list_emails, search_emails, archive_email]
)

agent.start("Check my inbox for unread messages from Bob")
Set either backend via env vars — same code works for both:
export AGENTMAIL_API_KEY="am_..."
export AGENTMAIL_INBOX_ID="you@agentmail.to"
2

With Configuration

Use the same tool with an agent — see Usage with Agent below, or pass env vars and options from the sections above.

​
Available Tools

These work with both backends. Just set env vars and go.
ToolSignatureAgentMailSMTP/IMAP
send_email(to, subject, body)✅ API✅ SMTP
list_emails(limit=10)✅ API✅ IMAP
read_email(message_id)✅ API✅ IMAP
reply_email(message_id, body)✅ API✅ SMTP (In-Reply-To)
search_emails(query, from_addr, subject, label, after_date, before_date, limit)✅ label/date✅ text/from/subject
archive_email(message_id)✅ label toggle✅ Gmail→All Mail
draft_email(to, subject, body)✅ drafts API✅ IMAP APPEND
forward_email(message_id, to, note)✅ API❌ (graceful fallback)
send_draft(draft_id)✅ drafts API❌ (graceful fallback)

​
AgentMail-Only Tools

ToolSignatureDescription
list_inboxes()List all inboxes for this API key
create_inbox(display_name)Create a new inbox
When a tool isn’t supported on the active backend, it returns a friendly fallback message — no errors.

​
Using Tool Profiles

from praisonaiagents import Agent
from praisonaiagents.tools import resolve_profiles

# AgentMail tools (send, list, read, reply)
agent = Agent(tools=resolve_profiles("email"))

# SMTP/IMAP tools (backward-compat aliases)
agent = Agent(tools=resolve_profiles("smtp_email"))

​
Backward-Compatible Aliases

These still work but the auto-detect tools above are preferred:
AliasMaps To
smtp_send_email_smtp_send_email (SMTP only)
smtp_read_inbox_smtp_list_emails (IMAP only)
smtp_search_inbox_smtp_search_emails (IMAP only)
smtp_archive_email_smtp_archive_email (IMAP only)
smtp_draft_email_smtp_draft_email (IMAP only)

​
Environment Variables

VariableBackendDefaultDescription
AGENTMAIL_API_KEYAgentMail—API key from agentmail.to
AGENTMAIL_INBOX_IDAgentMail—Inbox email address
EMAIL_ADDRESSSMTP/IMAP—Your email address
EMAIL_PASSWORDSMTP/IMAP—App Password (recommended)
EMAIL_SMTP_SERVERSMTP/IMAPAuto-detectedSMTP server hostname
EMAIL_IMAP_SERVERSMTP/IMAPAuto-detectedIMAP server hostname
If both AGENTMAIL_API_KEY and EMAIL_ADDRESS are set, AgentMail is preferred.

​
Gmail Setup

  1. Enable 2-Factor Authentication
  2. Generate App Password at Google Account
  3. Use App Password as EMAIL_PASSWORD

​
How It Works

​
Best Practices

For Gmail and Outlook, generate an App Password and set it as EMAIL_PASSWORD. Never store your real account password.
Set the env vars for one backend and use the auto-detect tools — the same agent code works for AgentMail or SMTP/IMAP.
Give the agent only the email tools it needs. A read-only assistant should not include send_email.
Use search_emails with from_addr, subject, or date filters so the agent processes a focused set of messages.

Email Bot

Deploy always-on email bots with event-driven modes

Messaging Bots

All supported messaging platforms