Open source AI email assistant. Use any LLM. Your inbox, your rules, your privacy.
MailFlow automatically classifies incoming emails, supports AI-assisted mail workflows, and can run with local or hosted LLMs.
MailFlow uses BaseHarbor as its recommended self-host runtime. BaseHarbor manages PostgreSQL, Valkey/Redis, application secrets and the backend network. MailFlow itself remains a normal containerized application and consumes only standard runtime contracts such as DATABASE_URL and REDIS_URL.
Prerequisites:
- Docker + Docker Compose v2
- BaseHarbor installed and its control plane healthy
bahaavailable inPATH
git clone https://github.com/mcpdev80/MAILFLOW-AI_MAILING.git
cd MAILFLOW-AI_MAILING
./mailflow installThe installer creates the local application configuration when needed, stores the required SECRET_KEY through BaseHarbor/OpenBao and then runs the equivalent of:
baha up
baha app doctorAfter installation, use the MailFlow CLI. It keeps the MailFlow-facing commands stable while delegating platform lifecycle operations to baha:
./mailflow start
./mailflow stop
./mailflow restart
./mailflow status
./mailflow doctor
./mailflow update
./mailflow backup
./mailflow restore .mailflow/backups/<backup> --yesThe primary Compose file, infrastructure/docker-compose.yml, contains only MailFlow workloads (api, worker, web, edge). PostgreSQL, Valkey and managed secrets are supplied by BaseHarbor and are intentionally not duplicated in the MailFlow stack.
| MailFlow command | Platform operation |
|---|---|
./mailflow start |
baha up |
./mailflow stop |
baha app down |
./mailflow restart |
baha app down + baha up |
./mailflow status |
baha app status |
./mailflow doctor |
baha app doctor |
backup and restore remain MailFlow-aware for now because they also cover MailFlow-owned attachment data. BaseHarbor-managed installations also use an operator-held OpenBao recovery file stored outside BaseHarbor-owned state. Database access is obtained from the standard BaseHarbor application environment contract. When BaseHarbor gains its complete application backup/restore API, this wrapper can delegate the infrastructure portion as well.
MailFlow can still run without BaseHarbor. The all-in-one legacy stack is intentionally isolated in:
infrastructure/docker-compose.standalone.yml
For an existing standalone installation:
MAILFLOW_RUNTIME=standalone ./mailflow start
MAILFLOW_RUNTIME=standalone ./mailflow stop
MAILFLOW_RUNTIME=standalone ./mailflow statusStandalone mode uses its own PostgreSQL and Redis containers. It is an explicit compatibility path, not the recommended self-host default.
MailFlow does not require a BaseHarbor SDK, login or proprietary database protocol. At runtime it consumes the same normal values it can receive from any deployment environment:
DATABASE_URL
REDIS_URL
SECRET_KEY
The API and Alembic migrations accept conventional PostgreSQL URLs (postgresql://...) and adapt them internally to the async SQLAlchemy driver used by MailFlow.
MailFlow has evolved substantially beyond the original upstream baseline. Current development includes, among other things:
- multi-mailbox and multi-user workflows
- AI-assisted classification and writing
- DecisionMemory-based learning from confirmed corrections
- review inbox, notifications, and daily summaries
- safe historical bulk review/apply workflows
- mailbox ownership and access controls
- composer, drafts, SMTP/XOAuth2 sending, and attachments
- unified inbox and core mail client actions
- TLS edge, custom certificate support, and network isolation
- localization support for German, English, and Spanish
- operational dashboard and search
MailFlow is developed independently in spare time and remains open source under AGPL-3.0 regardless of sponsorship.
If MailFlow saves you time, you use it regularly, or your organization depends on it, you can support continued development through GitHub Sponsors. Sponsorship helps fund development time, CI and test infrastructure, compatibility testing with local and hosted LLMs, security work, documentation, localization, and project infrastructure.
Sponsorship is completely optional and does not buy proprietary features, guaranteed feature delivery, priority support, an SLA, or a different software license.
See SPONSORS.md for the sponsorship policy and suggested support levels.
See docs/CONTRIBUTING.md for development setup and contribution guidance.
Development of this fork has included assistance from ChatGPT by OpenAI for planning, implementation support, testing, debugging, analysis, and documentation.
AI is used as a development tool, not identified as a legal author or copyright holder. The human maintainer directs, reviews, tests, selects, and integrates changes and assumes responsibility for those decisions.
For the detailed transparency and provenance statement, see AI_ASSISTANCE.md.
This repository is distributed under the GNU Affero General Public License v3.0 (AGPL-3.0). See LICENSE.
The AGPL permits commercial use, modification, distribution, and paid operation of the software, provided its conditions are met. In particular, a party that modifies a covered version and lets users interact with it remotely through a computer network must provide those users an opportunity to receive the Corresponding Source of that modified version as required by AGPL section 13.
There is no separate commercial-license requirement provided by this repository. No proprietary license to third-party upstream code is granted here.
This repository is derived from the original MailFlow project created by Jonatan Garcia / JonatanGhub and retains the upstream AGPL-3.0 licensing history.
Modification notice: this fork contains substantial modifications and new functionality made from September 2026 onward, including work authored by Marcel Pfingstgräf and other contributors.
Copyright in the original upstream portions remains with the respective upstream author(s). Copyright in later modifications and new contributions remains with the respective human author(s), where copyright subsists, unless explicitly assigned otherwise.
For detailed provenance and copyright scope, see NOTICE.md, COPYRIGHT.md, and AI_ASSISTANCE.md.
If you copy, fork, modify, redistribute, or operate a modified covered version of this project, review the full AGPL-3.0 terms in LICENSE. Among other things, do not remove applicable copyright, license, warranty, provenance, or modification notices that the license requires to remain intact.
The project name and upstream branding are not claimed here as exclusive trademarks of this fork.