email-manager

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

1. Enable 2FA on your Google account
2. Go to https://myaccount.google.com/apppasswords
3. Generate an app password for "Mail"
4. IMAP: imap.gmail.com:993 / SMTP: smtp.gmail.com:587

Outlook/Hotmail

1. Enable 2FA
2. Generate app password at https://account.live.com/proofs/manage
3. IMAP: outlook.office365.com:993 / SMTP: smtp.office365.com:587

iCloud

1. Generate app-specific password at https://appleid.apple.com
2. IMAP: imap.mail.me.com:993 / SMTP: smtp.mail.me.com:587

Store credentials:

EMAIL_ADDRESS=[e-mail]
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', '[e-mail]'], ['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'] = '[e-mail]'
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