gptmail

Email automation for gptme agents with shared communication utilities.

Overview

gptmail provides email automation capabilities including:

• CLI tools for reading, composing, and sending emails
• Background watcher for processing unreplied emails
• Shared communication utilities (auth, rate limiting, monitoring, state)
• Integration with Gmail via IMAP/SMTP

This package was originally developed as part of an agent workspace and upstreamed to gptme-contrib and upstreamed to gptme-contrib for use by all gptme agents.

Installation

Standalone (recommended for agents without uv workspace)

# Using uv tool
uv tool install git+https://github.com/gptme/gptme-contrib#subdirectory=packages/gptmail

# Or using pipx
pipx install git+https://github.com/gptme/gptme-contrib#subdirectory=packages/gptmail

From workspace

# From workspace root
uv pip install -e packages/gptmail

# Or using the Makefile
cd packages/gptmail && make install

Usage

CLI Tools

# Check for unreplied emails
gptmail check-unreplied

# Read specific email with thread
gptmail read <MESSAGE_ID> --thread

# Compose a reply
gptmail reply <MESSAGE_ID> "Your reply message"

# Send composed message
gptmail send <REPLY_MESSAGE_ID>

# See all commands
gptmail --help

Note: If installed in development mode, use python -m gptmail instead.

Background Watcher

# Run watcher in daemon mode
python -m gptmail.watcher

# Process one email and exit
python -m gptmail.watcher --mode one

Configuration

Environment variables:

• AGENT_EMAIL: Default sender email address
• EMAIL_ALLOWLIST: Comma-separated list of allowed sender addresses
• EMAIL_WORKSPACE: Path to email workspace directory

Architecture

The package structure:

• src/gptmail/ - Main package code
  • cli.py - Command-line interface
  • lib.py - Core email library
  • watcher.py - Background email processor
  • complexity.py - Email complexity analysis
  • communication_utils/ - Shared utilities (auth, rate limiting, etc.)
• tests/ - Test suite
• examples/ - Usage examples

Note: scripts/email Removed

The gptme-contrib/scripts/email/ directory has been removed. This package (gptmail) is now the canonical implementation. Key features:

• Proper Python package structure (src layout)
• Part of uv workspace
• Enhanced communication utilities
• Better test coverage
• Full maildir import/export support

Usage:

python -m gptmail check-unreplied
# Or if installed: gptmail check-unreplied

Contributing

Contributions welcome! Please ensure:

• Tests pass: make test
• Type checking passes: make typecheck
• Code is formatted: make format