MailPilot

Agent-operated CRM with Gmail as the communication layer.

Overview

MailPilot manages contacts, companies, and communication workflows through Gmail API. It is designed to be operated by AI agents -- Claude Code as the strategic orchestrator and an internal Pydantic AI agent for real-time reactive work.

Two-Layer Intelligence

Claude Code -- strategic orchestrator. Creates workflows, assigns contacts, reviews outcomes, generates reports. Operates the system via CLI.
Internal Pydantic AI agent -- subordinate tactical executor. Handles inbound email classification, auto-replies, and follow-up scheduling within workflows.

Key Capabilities

Contact and company management -- track relationships, tag for segmentation, annotate with notes
Activity timeline -- unified chronological log of all interactions per contact
Email workflows -- inbound auto-reply and outbound campaigns via Gmail API with service account delegation
Task scheduling -- deferred agent work with scheduled execution for long-running processes
Reporting -- Claude Code queries the database and generates activity summaries, relationship health, and campaign effectiveness reports

Install

MailPilot ships on PyPI as mailpilot-crm. The package installs the mailpilot command. Python 3.14 or later is required.

Install with uv:

uv tool install mailpilot-crm

Or install with pip:

pip install mailpilot-crm

Verify the install:

mailpilot --version

Quick Start

MailPilot needs PostgreSQL 18 and a Google service account with domain-wide delegation for the Gmail API.

Create the database. MailPilot provisions the schema on first connection:

createdb mailpilot

Point MailPilot at the database:

mailpilot config set database_url postgresql://localhost/mailpilot

Set the Google service account credentials:

mailpilot config set google_application_credentials /path/to/service-account.json

Set the Anthropic API key:

mailpilot config set anthropic_api_key sk-ant-...

Create the Gmail account MailPilot operates:

mailpilot account create --email user@example.com --display-name "User Name"

Sync the inbox:

mailpilot account sync

Start the event-driven sync loop:

mailpilot run

Release

Human release notes live in root CHANGELOG.md (Keep a Changelog). During development, append user-facing work under ## Unreleased in ### Added / ### Changed / ### Fixed. Empty Unreleased (no bullets) hard-fails the release - nothing to ship.

make release patch   # or minor | major

make release is the sole release path (never local gh release create):

make check (ruff, basedpyright, pytest)
Fail if ## Unreleased has no bullets
Bump pyproject.toml version (major | minor | patch)
Promote Unreleased body to ## [vX.Y.Z] - YYYY-MM-DD, leave an empty ## Unreleased
Commit CHANGELOG.md + pyproject.toml + uv.lock together, tag vX.Y.Z, push

GitHub Actions on tag v* re-runs CI, builds sdist+wheel, publishes to PyPI (OIDC), and creates a GitHub Release whose notes are the promoted CHANGELOG section for that tag (plus the artifacts).

License

Licensed under the Apache License, Version 2.0. See LICENSE for the full text.

Release files for mailpilot-crm 0.25.1

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for mailpilot-crm 0.25.1
File	Size	Uploaded
mailpilot_crm-0.25.1.tar.gz	242.0 kB	Aug 14, 2026	Details

Built distribution (wheel)

Table of built distributions (wheels) for mailpilot-crm 0.25.1
File	Interpreter	ABI	Platform	Reset
mailpilot_crm-0.25.1-py3-none-any.whl 261.5 kB Aug 14, 2026	Python 3	none	any	Details

Total release size: 503.5 kB

Release files / mailpilot_crm-0.25.1.tar.gz

Download URL	mailpilot_crm-0.25.1.tar.gz
Size	242.0 kB
Tags	Source
SHA-256 checksum How to use checksums	`2b36356006900f56b1910e7a5032573a699ca1da3cf363ffe9eefd4ca6624479`
BLAKE2b-256 checksum How to use checksums	`0b5dfb8e94e0e9830d44ec2323110791a84a61c6a8a2c53903b814dbf8e96b96`
Upload date	Aug 14, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	Yes
Uploaded via	`twine/7.0.0 CPython/3.13.14`

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Identity

Publishing platform: GitHub Actions
Publishing repository: github.com/kborovik/mailpilot
Publishing commit: github.com/kborovik/mailpilot/tree/584fb233ddf5d4824218e091e548f2eb5247fb75

Workflow

Publishing configuration: github.com/kborovik/mailpilot/blob/584fb233ddf5d4824218e091e548f2eb5247fb75/.github/workflows/release.yml
Publishing logs: github.com/kborovik/mailpilot/actions/runs/31761557246/attempts/1

Artifact

Subject: mailpilot_crm-0.25.1.tar.gz
SHA-256 checksum: 2b36356006900f56b1910e7a5032573a699ca1da3cf363ffe9eefd4ca6624479 Verifying attestations

Release files / mailpilot_crm-0.25.1-py3-none-any.whl

Download URL	mailpilot_crm-0.25.1-py3-none-any.whl
Size	261.5 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`272139f22e8a4edf7d43520599718880eb63369f92d6bcf820234f62c77d3163`
BLAKE2b-256 checksum How to use checksums	`3db84cd86e60889321466420deee77ad3526f822122131f17a6f5aaa31053960`
Upload date	Aug 14, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	Yes
Uploaded via	`twine/7.0.0 CPython/3.13.14`

Provenance

Identity

Publishing platform: GitHub Actions
Publishing repository: github.com/kborovik/mailpilot
Publishing commit: github.com/kborovik/mailpilot/tree/584fb233ddf5d4824218e091e548f2eb5247fb75

Workflow

Publishing configuration: github.com/kborovik/mailpilot/blob/584fb233ddf5d4824218e091e548f2eb5247fb75/.github/workflows/release.yml
Publishing logs: github.com/kborovik/mailpilot/actions/runs/31761557246/attempts/1

Artifact

Subject: mailpilot_crm-0.25.1-py3-none-any.whl
SHA-256 checksum: 272139f22e8a4edf7d43520599718880eb63369f92d6bcf820234f62c77d3163 Verifying attestations