Metadata-Version: 2.4
Name: gptmail
Version: 0.1.0
Summary: Email automation for gptme agents with shared communication utilities
Project-URL: Homepage, https://github.com/gptme/gptme-contrib
Project-URL: Repository, https://github.com/gptme/gptme-contrib
Project-URL: Issues, https://github.com/gptme/gptme-contrib/issues
Author-email: gptme contributors <gptme@superuserlabs.org>
License-Expression: MIT
Keywords: ai-agents,automation,cli,email,gptme
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Communications :: Email
Classifier: Topic :: Utilities
Requires-Python: >=3.10
Requires-Dist: click>=8.0
Requires-Dist: markdown>=3.4
Requires-Dist: python-dateutil>=2.8
Requires-Dist: requests>=2.28
Provides-Extra: test
Requires-Dist: mypy>=1.0; extra == 'test'
Requires-Dist: pytest-cov>=4.0; extra == 'test'
Requires-Dist: pytest>=7.0; extra == 'test'
Requires-Dist: ruff>=0.1; extra == 'test'
Description-Content-Type: text/markdown

# 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)

```bash
# 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

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

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

## Usage

### CLI Tools

```bash
# 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

```bash
# 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:
```bash
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`
