Email

Send, read, search, reply, archive, and draft emails — auto-detects AgentMail or SMTP/IMAP backend

Give your agents email superpowers. Just set env vars — tools auto-detect the right backend.

Quick Start

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:

AgentMail (API)

export AGENTMAIL_API_KEY="am_..."
export AGENTMAIL_INBOX_ID="[e-mail]"

Gmail / Outlook (SMTP)

export EMAIL_ADDRESS="[e-mail]"
export EMAIL_PASSWORD="xxxx xxxx xxxx xxxx"  # App Password

---

Available Tools

Auto-Detect Tools (Recommended)

These work with both backends. Just set env vars and go.

Tool	Signature	AgentMail	SMTP/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

Tool	Signature	Description
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:

Alias	Maps 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

Variable	Backend	Default	Description
AGENTMAIL_API_KEY	AgentMail	—	API key from agentmail.to
AGENTMAIL_INBOX_ID	AgentMail	—	Inbox email address
EMAIL_ADDRESS	SMTP/IMAP	—	Your email address
EMAIL_PASSWORD	SMTP/IMAP	—	App Password (recommended)
EMAIL_SMTP_SERVER	SMTP/IMAP	Auto-detected	SMTP server hostname
EMAIL_IMAP_SERVER	SMTP/IMAP	Auto-detected	IMAP 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

---

Related

Email Bot

Deploy always-on email bots with event-driven modes

Messaging Bots

All supported messaging platforms