{"id":26563668,"url":"https://github.com/jbchouinard/llmailbot","last_synced_at":"2026-05-09T17:43:52.901Z","repository":{"id":283576881,"uuid":"950312753","full_name":"jbchouinard/llmailbot","owner":"jbchouinard","description":"A service that enables chatting with LLMs via email.","archived":false,"fork":false,"pushed_at":"2025-03-21T01:13:21.000Z","size":387,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-03-21T01:15:22.791Z","etag":null,"topics":["email","langchain","langchain-python","large-language-models","llm","llm-serving","llms","python"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/jbchouinard.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2025-03-18T00:59:43.000Z","updated_at":"2025-03-21T01:13:24.000Z","dependencies_parsed_at":"2025-03-21T01:15:30.739Z","dependency_job_id":"0fd4aea4-fb3c-417b-93f4-90dc228f9887","html_url":"https://github.com/jbchouinard/llmailbot","commit_stats":null,"previous_names":["jbchouinard/llmailbot"],"tags_count":2,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jbchouinard%2Fllmailbot","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jbchouinard%2Fllmailbot/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jbchouinard%2Fllmailbot/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jbchouinard%2Fllmailbot/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/jbchouinard","download_url":"https://codeload.github.com/jbchouinard/llmailbot/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":244982060,"owners_count":20542301,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["email","langchain","langchain-python","large-language-models","llm","llm-serving","llms","python"],"created_at":"2025-03-22T16:16:43.624Z","updated_at":"2026-05-09T17:43:47.875Z","avatar_url":"https://github.com/jbchouinard.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# LLMailBot\n\n[![CI](https://github.com/jbchouinard/llmailbot/actions/workflows/ci.yml/badge.svg)](https://github.com/jbchouinard/llmailbot/actions/workflows/ci.yml)\n[![Docker](https://img.shields.io/docker/v/jbchouinard/llmailbot?logo=docker\u0026label=Docker%20Hub)](https://hub.docker.com/r/jbchouinard/llmailbot)\n[![PyPI](https://img.shields.io/pypi/v/llmailbot?logo=python\u0026logoColor=white)](https://pypi.org/project/llmailbot/)\n\nLLMailBot is a service that enables chatting with Large Language Models (LLMs) via email. It connects to an email account using IMAP/SMTP protocols, then automatically responds to incoming emails using LLM chat models like GPT-4, Claude, or other compatible models.\n\n**⚠️ IMPORTANT: LLMailBot may delete emails in the connected account. Always use a dedicated email account created specifically for this purpose, never your personal email account.**\n\nNote that sending programatically generated emails to third parties may be against the terms of service of your email provider.\n\n## Key Features\n\n- **LLM Integration**: Uses [LangChain chat models](https://python.langchain.com/docs/integrations/chat) to provide compatibility with most mainstream LLMs\n- **Security**: Includes basic security features such as rate limiting and address filtering\n- **Dynamic Configuration**: Supports multiple model configurations based on pattern-matching email addresses\n- **Scalability**: Horizontally scalable architecture using Redis queues for high-volume deployments\n- **Flexible Deployment**: Run using Pipx, Docker, or Docker Compose depending on your needs\n\n## Security Considerations\n\n**⚠️ WARNING: Since generally anyone can email anyone, using LLMailBot means you risk letting unauthorized people indirectly use your LLM API keys or access your self-hosted LLM.**\n\nLLMailBot has basic address filtering, but it is not extremely secure:\n- LLMailBot will only reply to emails from addresses in the `AllowFrom` list configured in your settings.\n- However, the `AllowFrom` filter only checks the From header of incoming emails, which is vulnerable to spoofing.\n\n### Email Spoofing\n\nEmail spoofing is possible because email From headers are just something the sender\nwrites, they don't need to match where the email actually comes from.\n\nMail servers use technologies like [SPF, DKIM, and DMARC](https://www.fastmail.com/blog/spf-dkim-dmarc/)\nto block malicious spoofed emails, but it's not perfect.\nEmail spoofing tends to work due to misconfigured mail servers or domains.\nSo if you only allow addresses from major email providers you should be relatively safe.\n\nTo be even more safe, you may want to only allow emails from the same domain as the service.\nFor example, if LLMailBot is set up on myservice@example.com, only allow myname@example.com,\nmyfriend@example.com, etc. It *should* be hard to trick a mail server\ninto accepting spoofed emails claiming to be from its own domain.\n\nIt's much more likely that example.com could be tricked into accepting spoofed emails\nfrom sketchy domains or the domains of small businesses with misconfigured domains/servers.\n\n### Security Recommendations\n\nI developed LLMailBot for my own personal use. Use it at your own risk.\n\n- **Never connect LLMailBot to a personal email account** - it may delete your emails\n- **Create a dedicated email account** specifically for LLMailBot usage\n- **Configure restrictive AllowFrom settings** - only allow specific addresses from domains you trust\n- **Set up API key limitations** - use LLM API keys with rate or cost limits you're comfortable with\n- **Avoid sensitive information** - don't send sensitive data via email or include it in system prompts\n\n## Limitations\n\nOnly plain text emails are supported. But for accessibility reasons,\nwell-behaved email clients **should** automatically include a text/plain alternative\nversion when sending richly formatted emails.\n\nLLMailBot does not store emails or track conversations.\n**Usually**, when replying, email clients copy the entire chain in\nthe reply. LLMailBot does the same when it replies.\nThat way the context of the conversation is saved in the emails themselves.\n\nEmails are minimally preprocessed, so the quality of responses\ndepends on the ability of models to \"understand\" nested quoted replies.\nMessages in the chain are usually ordered from newest to oldest, unlike chat messages.\nIt seems to work OK with the models I tested, but your mileage may vary.\n\n## Getting started\n\n### Installation with Pipx\n\n1. **Install LLMailBot**:\n   ```bash\n   # Install from PyPI (recommended)\n   pipx install llmailbot\n   \n   # Or install directly from GitHub\n   pipx install git+https://github.com/jbchouinard/llmailbot.git\n   ```\n\n2. **Add LangChain provider packages** for your preferred LLMs:\n   ```bash\n   # Install only the providers you need\n   pipx inject llmailbot langchain-openai langchain-anthropic langchain-ollama\n   ```\n\n3. **Create your configuration**:\n   ```bash\n   # Interactive configuration\n   llmailbot config interactive\n   \n   # Or generate an example configuration and edit it manually\n   llmailbot config example\n   # Then edit the generated config.yaml file\n   ```\n   \n   If you place the config in a [standard location](#yaml-configuration-file-locations), you can omit the `--config` option.\n\n4. **Start the service**:\n   ```bash\n   # Run with your configuration file\n   llmailbot --config path/to/config.yaml run\n   ```\n\n### Deployment with Docker\n\n1. **Prepare your configuration**:\n   - Use the interactive configuration command to create your config file:\n     ```bash\n     llmailbot config interactive\n     ```\n   - Or copy and edit the example configuration:\n     ```bash\n     llmailbot config example\n     # Then edit the generated config.yaml file\n     ```\n\n2. **Choose a Docker image variant**:\n\n   #### Option A: `all` variant (larger but more convenient)\n   \n   The `all` variant includes these langchain provider packages pre-installed:\n   - langchain-ai21 - AI21 models (Jurassic)\n   - langchain-anthropic - Anthropic models (Claude)\n   - langchain-aws - AWS Bedrock models\n   - langchain-azure-ai - Azure OpenAI models\n   - langchain-cohere - Cohere models\n   - langchain-fireworks - Fireworks AI models\n   - langchain-google-genai - Google Gemini models\n   - langchain-google-vertexai - Google Vertex AI models\n   - langchain-groq - Groq models (LLaMA, Mixtral)\n   - langchain-mistralai - Mistral AI models\n   - langchain-nvidia-ai-endpoints - NVIDIA AI models\n   - langchain-openai - OpenAI models (GPT-3.5, GPT-4, etc.)\n   - langchain-together - Together AI models\n   - langchain-xai - XAI models\n\n   Run the `all` variant (works out of the box with most popular models):\n   ```bash\n   docker run -d --name llmailbot \\\n     -v /absolute/path/to/config.yaml:/app/config.yaml \\\n     jbchouinard/llmailbot:all\n   ```\n\n   #### Option B: `slim` variant (smaller but requires extra setup)\n   \n   The `slim` variant has no langchain provider packages pre-installed, making it smaller but requiring additional setup:\n\n   1. Create a `requirements.txt` file with your needed providers, e.g.:\n      ```\n      # requirements.txt\n      langchain-openai\n      langchain-anthropic\n      ```\n\n   2. Run the `slim` variant with your requirements:\n      ```bash\n      docker run -d --name llmailbot \\\n        -v /absolute/path/to/config.yaml:/app/config.yaml \\\n        -v /absolute/path/to/requirements.txt:/app/requirements.txt \\\n        jbchouinard/llmailbot:slim\n      ```\n\n### Deployment with Docker Compose\n\nThe repo has an example [docker-compose.yaml](./examples/docker-compose/docker-compose.yaml),\nusing inline configuration.\n\n\n2. **Start the services**:\n   ```bash\n   cd docker-compose\n   docker-compose up -d\n   ```\n\n3. **Scale services horizontally** (optional):\n   ```bash\n   # Run 3 worker instances for parallel processing\n   docker-compose up -d --scale worker=3\n   \n   # You can scale any service as needed\n   docker-compose up -d --scale fetcher=2 --scale worker=5 --scale sender=2\n   ```\n\nSee [examples/config.yaml](./examples/config.yaml) for detailed configuration options and explanations.\n\n### Deployment with Docker Swarm\n\nThe repo contains two example stacks for deployment with `docker stack deploy`:\n1. [docker-stack.simple.yaml](./examples/docker-swarm/docker-stack.simple.yaml) - Single container with in-memory queues\n2. [docker-stack.redis.yaml](./examples/docker-swarm/docker-stack.redis.yaml) - Multi-containers with Redis queues\n\nThey are the better starting point for a production-style deployment as they use docker secrets for\nall sensitive config.\n\n### Development Setup with Poetry\n\n1. **Clone the repository**:\n   ```bash\n   git clone https://github.com/jbchouinard/llmailbot.git\n   cd llmailbot\n   ```\n\n2. **Install dependencies**:\n   ```bash\n   # Install base dependencies\n   poetry install\n   \n   # (Optional) Add additional langchain providers\n   poetry add --group langchain langchain-ollama\n   \n   # Install with langchain group\n   poetry install --with langchain\n   ```\n\n3. **Run the application**:\n   ```bash\n   # View available commands\n   poetry run llmailbot --help\n   \n   # Run with a config file\n   poetry run llmailbot --config path/to/config.yaml run\n   ```\n\n## Configuration Options\n\n**⚠️ WARNING: If `RepliedFolder` or `BlockedFolder` are set to null, LLMailBot will delete emails instead of moving them.**\n\nAll configuration options are documented in [examples/config.yaml](./examples/config.yaml) with explanations and examples.\n\n### Configuration Sources (in order of precedence)\n\nllmailbot loads configuration from multiple sources:\n\n1. **Constructor Arguments**: Values passed directly to the `LLMailBotConfig` constructor\n2. **YAML File**: Loaded from one of several possible locations\n3. **Secret Files**: Loaded from `/run/secrets` and `/var/run/llmailbot/secrets/`\n\n### YAML Configuration File Locations\n\nIf the config file location is not specified by the --config CLI options,\nthe app searches for a YAML configuration file in the following locations (in order):\n\n1. `./config.yaml` (current directory)\n2. `~/.config/llmailbot/config.yaml` (Unix convention)\n3. OS-specific conventional location (using the `config-path` package):\n   - **Windows**: Uses `%APPDATA%\\net.pigeonland.llmailbot.yaml` (typically `C:\\Users\\\u003cusername\u003e\\AppData\\Roaming\\net.pigeonland.llmailbot.yaml`)\n   - **macOS**: `~/Library/Preferences/net.pigeonland.llmailbot.yaml`\n   - **Linux/Other**: `~/.config/net.pigeonland.llmailbot.yaml` (follows XDG Base Directory Specification)\n\n### Secret Files\n\n#### Configuration\n\nConfiguration can be loaded from secrets files (e.g. produced by Docker Secrets).\n\nSecret files are loaded from `/run/secrets` or `/var/run/secrets/llmailbot/`. They must be in JSON format.\n\nEach top-level block in the YAML config corresponds to a secret file:\n\n| Configuration Section       | Secret File Path                      |\n|-----------------------------|---------------------------------------|\n| Models                      | `secrets/models`                      |\n| ChatModelConfigurableFields | `secrets/chatmodelconfigurablefields` |\n| SMTP                        | `secrets/smtp`                        |\n| IMAP                        | `secrets/imap`                        |\n| Security                    | `secrets/security`                    |\n| ReceiveQueue                | `secrets/receivequeue`                |\n| SendQueue                   | `secrets/sendqueue`                   |\n\n#### API Keys\n\nLLMailBot supports loading provider API keys from files by setting `PROVIDER_API_KEY_FILE` environment variables.\nFor example, to load OpenAI API keys from a Docker secret, you could set set:\n\n```yaml\nservices:\n  llmailbot:\n    ...\n    secrets:\n      - source: openai_api_key\n        target: /run/secrets/openai_api_key\n    environment:\n      ...\n      - OPENAI_API_KEY_FILE=/run/secrets/openai_api_key\n```\n\n## Development\n\n### CI/CD\n\nThis project uses GitHub Actions for continuous integration and delivery:\n\n- **CI Workflow**: Runs on push to main and pull requests\n  - Linting with ruff\n  - Code formatting with ruff format\n  - Unit tests with pytest\n  - Docker build test\n\n- **Docker Publish Workflow**: Runs on push to main, tags with 'v*' pattern, and releases\n  - Builds and pushes Docker images to Docker Hub\n  - Creates two variants: `slim` (without langchain packages) and `all` (with langchain packages)\n\n### Development Workflow\n\n#### Code Quality\n\nApply linting and formatting fixes locally:\n```bash\n# Run linting checks and auto-fix issues\npoetry run ruff check --fix\n\n# Format code according to project standards\npoetry run ruff format\n```\n\n#### Testing\n\nRun the test suite locally:\n```bash\n# Run all tests\npoetry run pytest tests\n\n# Run with verbose output\npoetry run pytest -v tests\n\n# Run a specific test file\npoetry run pytest tests/test_specific_module.py\n```\n\n## License\n\nThis project is licensed under the MIT License - see the [LICENSE](./LICENSE) file for details.\n\nCopyright 2025 Jerome Boisvert-Chouinard\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjbchouinard%2Fllmailbot","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjbchouinard%2Fllmailbot","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjbchouinard%2Fllmailbot/lists"}