| name | email-manager |
| description | Read, search, and send emails from your agent via IMAP and SMTP. |
Email Manager
Read, search, and send emails from your agent via IMAP and SMTP.
Category: communication, productivity
API Key Required: Yes (email credentials or app password)
What It Does
Full email access: check your inbox, read messages, search by sender/subject/date, send replies, compose new emails, and get daily summaries. Works with Gmail, Outlook, Yahoo, iCloud, and any IMAP/SMTP provider.
Setup
Gmail
- Enable 2FA on your Google account
- Go to https://myaccount.google.com/apppasswords
- Generate an app password for "Mail"
- IMAP:
imap.gmail.com:993 / SMTP: smtp.gmail.com:587
Outlook/Hotmail
- Enable 2FA
- Generate app password at https://account.live.com/proofs/manage
- IMAP:
outlook.office365.com:993 / SMTP: smtp.office365.com:587
iCloud
- Generate app-specific password at https://appleid.apple.com
- IMAP:
imap.mail.me.com:993 / SMTP: smtp.mail.me.com:587
Store credentials:
EMAIL_ADDRESS=you@gmail.com
EMAIL_PASSWORD=app_password_here
IMAP_SERVER=imap.gmail.com
SMTP_SERVER=smtp.gmail.com
Install dependencies
pip3 install imapclient
Agent Commands
Check inbox (latest 10 emails)
python3 -c "
from imapclient import IMAPClient
server = IMAPClient('$IMAP_SERVER', ssl=True)
server.login('$EMAIL_ADDRESS', '$EMAIL_PASSWORD')
server.select_folder('INBOX')
messages = server.search(['ALL'])[-10:]
for uid, data in server.fetch(messages, ['ENVELOPE']).items():
env = data[b'ENVELOPE']
frm = env.from_[0] if env.from_ else None
sender = f'{frm.mailbox.decode()}@{frm.host.decode()}' if frm else 'unknown'
subject = env.subject.decode() if env.subject else '(no subject)'
date = env.date.strftime('%Y-%m-%d %H:%M') if env.date else ''
print(f'{date:20s} {sender:30s} {subject}')
server.logout()
"
Read a specific email
python3 -c "
from imapclient import IMAPClient
import email
from email.header import decode_header
server = IMAPClient('$IMAP_SERVER', ssl=True)
server.login('$EMAIL_ADDRESS', '$EMAIL_PASSWORD')
server.select_folder('INBOX')
messages = server.search(['ALL'])
uid = messages[-1] # latest message, change index as needed
raw = server.fetch([uid], ['RFC822'])[uid][b'RFC822']
msg = email.message_from_bytes(raw)
subject = str(decode_header(msg['Subject'])[0][0], 'utf-8') if isinstance(decode_header(msg['Subject'])[0][0], bytes) else decode_header(msg['Subject'])[0][0]
print(f'From: {msg[\"From\"]}')
print(f'Subject: {subject}')
print(f'Date: {msg[\"Date\"]}')
print('---')
if msg.is_multipart():
for part in msg.walk():
if part.get_content_type() == 'text/plain':
print(part.get_payload(decode=True).decode('utf-8', errors='replace'))
break
else:
print(msg.get_payload(decode=True).decode('utf-8', errors='replace'))
server.logout()
"
Search emails
python3 -c "
from imapclient import IMAPClient
server = IMAPClient('$IMAP_SERVER', ssl=True)
server.login('$EMAIL_ADDRESS', '$EMAIL_PASSWORD')
server.select_folder('INBOX')
# Search by subject
messages = server.search(['SUBJECT', 'invoice'])
# Other searches: ['FROM', 'name@example.com'], ['SINCE', '20-Feb-2026'], ['UNSEEN']
for uid, data in server.fetch(messages[-10:], ['ENVELOPE']).items():
env = data[b'ENVELOPE']
frm = env.from_[0] if env.from_ else None
sender = f'{frm.mailbox.decode()}@{frm.host.decode()}' if frm else 'unknown'
subject = env.subject.decode() if env.subject else '(no subject)'
print(f'{sender:30s} {subject}')
server.logout()
"
Check unread count
python3 -c "
from imapclient import IMAPClient
server = IMAPClient('$IMAP_SERVER', ssl=True)
server.login('$EMAIL_ADDRESS', '$EMAIL_PASSWORD')
server.select_folder('INBOX')
unseen = server.search(['UNSEEN'])
print(f'{len(unseen)} unread emails')
server.logout()
"
Send an email
python3 -c "
import smtplib
from email.mime.text import MIMEText
from email.mime.multipart import MIMEMultipart
msg = MIMEMultipart()
msg['From'] = '$EMAIL_ADDRESS'
msg['To'] = 'recipient@example.com'
msg['Subject'] = 'Subject here'
msg.attach(MIMEText('Email body text here', 'plain'))
with smtplib.SMTP('$SMTP_SERVER', 587) as server:
server.starttls()
server.login('$EMAIL_ADDRESS', '$EMAIL_PASSWORD')
server.send_message(msg)
print('Email sent!')
"
Examples
User: "Check my email"
→ List last 10 emails with sender, subject, date
User: "Any emails from Amazon?"
→ Search FROM 'amazon', list results
User: "Read the latest email"
→ Fetch and display the newest message body
User: "How many unread emails do I have?"
→ Search UNSEEN, report count
User: "Reply to that email saying I'll be there at 3pm"
→ Compose reply to the last read email
Constraints
- App passwords required for Gmail/Outlook (regular passwords won't work with 2FA)
- IMAP shows server-side state — changes sync across all devices
- Sending emails is an EXTERNAL ACTION — always confirm with the user before sending
- Large attachments may timeout — keep to text/plain for reading
- Some corporate email may block IMAP access