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 (optional; default is
postgresql://localhost/mailpilot). The URL is bootstrap-only -- env
MAILPILOT_DATABASE_URL or a cwd .env -- not config set:
export MAILPILOT_DATABASE_URL=postgresql://localhost/mailpilot
Set the Google service account JSON (or omit for Application Default Credentials):
mailpilot config set google_application_credentials "$(cat /path/to/service-account.json)"
Set the xAI API key (default provider):
mailpilot config set xai_api_key xai-...
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
## Unreleasedhas no bullets - Bump
pyproject.tomlversion (major|minor|patch) - Promote Unreleased body to
## [vX.Y.Z] - YYYY-MM-DD, leave an empty## Unreleased - Commit
CHANGELOG.md+pyproject.toml+uv.locktogether, tagvX.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
Copyright 2026 Konstantin Borovik.
Licensed under the Apache License, Version 2.0. See LICENSE for the full text.
1 maintainer
Release files for mailpilot-crm 0.34.1
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| mailpilot_crm-0.34.1.tar.gz | 274.1 kB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| mailpilot_crm-0.34.1-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 595.0 kB
Release files / mailpilot_crm-0.34.1.tar.gz
| Download URL | mailpilot_crm-0.34.1.tar.gz |
|---|---|
| Size | 274.1 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
dccb5620133646c954c219ed7da571e7b3c6b2773c9c1980acee37722c50b565
|
|
BLAKE2b-256 checksum How to use checksums |
43714f9058805af48cf859a8fe37acc84c4818c02f5cd8b218a4b00c545b808b
|
| Upload date | |
|
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.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Aug 26, 2026.
Transparency logRelease files / mailpilot_crm-0.34.1-py3-none-any.whl
| Download URL | mailpilot_crm-0.34.1-py3-none-any.whl |
|---|---|
| Size | 320.9 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
b0109e666e391f66b18884da91990fe8954ca2263cc260dd4191ae66d3f25841
|
|
BLAKE2b-256 checksum How to use checksums |
a95c74549d571802742744b4ed12347c8a91824a9c6a20b817e105dda157101a
|
| Upload date | |
|
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.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Aug 26, 2026.
Transparency log
