Telegram Multi-Account Message Sender

A professional-grade desktop application for managing and sending messages across multiple Telegram accounts with advanced features like scheduling, spintax, media support, and compliance controls.

Install

pip install telegram-multi-account-sender

Then launch with telegram-sender or python -m app.cli. Full setup: docs/quick-start.md · docs/installation.md · PyPI.

---

☁️ SendGram — Hosted Telegram Campaign SaaS

Run multi-account Telegram outreach in the cloud — no desktop install, no server maintenance.

SendGram is the managed SaaS edition built on the same pacing discipline and campaign workflow as this project. Teams that outgrow a single desktop get multi-tenant hosting, role-based access, and production-grade delivery infrastructure.

Why teams choose SendGram over self-hosting

• Multi-tenant Telegram campaign automation — connect accounts, recipients, and paced sends from one secure web app
• Team collaboration built in — owner, admin, and operator roles with per-org encryption at rest
• Hosted delivery workers — background Telethon send jobs, scheduling, pause/resume, and delivery analytics without managing Fly.io or VPS
• Enterprise-ready integrations — API keys, HMAC webhooks, and dual billing (LicenseChain Pay)
• Self-serve growth tools — recipient segments, campaign templates, usage alerts, and guided onboarding
• Production SLA path — live at sendgram.pro with CI/CD, Supabase Postgres, and platform admin controls

Prefer the desktop app? Keep using TMMS locally. Need a team, API, or always-on delivery? SendGram is the upgrade path.

Start free — no credit card required

→ Launch SendGram

Compare plans & features

→ View pricing

---

✨ Features

🚀 Core Functionality

• Multi-Account Management: Manage multiple Telegram accounts simultaneously with proxy support
• Account Import Methods: Add accounts via phone number or by importing Telethon session files
• Proxy Support: Full proxy support (HTTP, HTTPS, SOCKS4, SOCKS5) with connection testing
• Campaign Management: Create, schedule, and manage message campaigns
• Template System: Create and manage message templates with spintax support
• Recipient Management: Organize and manage recipient lists
• Message Testing: Test messages before sending campaigns
• Comprehensive Logging: Track all activities with detailed logs

🎨 User Interface

• Modern desktop shell: Left navigation rail, page headers, and dense dark surfaces with a VoxHash teal accent (SendGram-ready branding)
• Multi-Language Support: Available in 13 languages (English, French, Spanish, Chinese, Japanese, German, Russian, Estonian, Portuguese, Korean, Catalan, Basque, Galician)
• Responsive Design: Adapts to different window sizes with a fixed nav rail and flexible content stack
• Themes: Dark (default dense look), light, Dracula, high-contrast, and auto (follow system)

🔧 Advanced Features

• Spintax Support: Create message variations using spintax syntax with real-time processing
• AI Copy Tools (optional): Rewrite, spintax conversion, and variations via your own API key with provider presets (OpenAI-compatible, Azure OpenAI, Anthropic Messages API; no AI SDK dependency); UI strings localized in all 13 languages
• Plugin Registry: Browse a curated marketplace catalog (Ed25519-signed official JSON), install SHA-256–verified .py plugins into app_data/plugins/, then enable from the Plugins tab; developers use plugin-catalog-entry / plugin-validate / plugin-catalog-sign (filter + analytics templates under registry/templates/)
• Web Companion (optional, read-only): Local stdlib HTTP monitor with live SVG charts (activity, status, campaigns, health), account/campaign tables, and recent activity (telegram-sender web-monitor or Settings → Start & Open); optional WEB_COMPANION_AUTO_START / Auto-start with GUI (background, no browser); optional Bearer token auth (required for non-localhost); reverse-proxy guidance in docs; no send/control routes
• Cloud Backup: Encrypted .tmas-backup.zip upload/restore to Google Drive, S3-compatible storage (AWS, MinIO, R2, Wasabi, B2), Dropbox, OneDrive, or Proton Drive (official CLI session) via Settings → Cloud Backup (pip install '.[cloud]' for Drive/S3; Dropbox/OneDrive use stdlib HTTP; Proton Drive needs proton-drive on PATH)
• Operator handoff: Full workspace export/import (DB + sessions) via Settings → Export for Handoff…, or selective Export Templates/Campaigns… (entities.json; merge or replace on import). CLI: handoff-export / handoff-import with --entities and --mode. Multi-user roles belong to SendGram
• Native Accelerator (optional): Rust sidecar for parallel spintax batches and multi-account pacing (lower prep CPU/RAM; auto Python fallback)
• A/B Testing: Test different message variants with statistical analysis
• Scheduling: Schedule campaigns for specific times with timezone support
• Rate Limiting: Respect Telegram's rate limits with intelligent throttling
• Retry Logic: Automatic retry for failed messages with exponential backoff
• Media Support: Send text, media, and combined messages with URL support
• Log Management: Comprehensive logging with "Delete All Logs" functionality
• Windows Integration: Start with Windows option for seamless user experience

🛡️ Safety & Compliance

• Account Warmup: Gradual account warming to avoid spam detection
• Rate Limiting: Built-in rate limiting to prevent account bans
• Error Handling: Comprehensive error handling and recovery
• Dry Run Mode: Test campaigns without sending actual messages
• Compliance Controls: Built-in controls for responsible messaging
• Security posture: Documented threat model for proxies/shared machines; security-check / security-harden for session and .env permissions; weekly pip-audit CI (see SECURITY.md)

🖼️ Screenshots

Main Interface - Campaigns

Campaign Management Sidebar navigation into campaigns with scheduling, status tracking, and bulk operations

Template System

Template System Advanced template management with spintax support and A/B testing capabilities

Settings & Configuration

Settings Complete settings management with multi-language support, themes, and safety controls

Message Testing

Testing Interface Message testing functionality with real-time preview and validation

🚀 Quick Start

Prerequisites

• Python 3.10 or higher
• PyQt5
• Telegram API credentials (API ID and API Hash)

Installation

Option 1: Using pip (Recommended)

pip install telegram-multi-account-sender

Option 2: From source

git clone https://github.com/VoxHash/Telegram-Multi-Account-Message-Sender.git
cd Telegram-Multi-Account-Message-Sender
pip install -r requirements.txt
# Optional: Rust accelerator — download tmms_native-linux-x86_64 from Releases
# into bin/tmms_native, or build with: ./native/build.sh
python main.py

Option 3: Using Docker

# Build the Docker image
docker build -t telegram-sender .

# Run the container
docker run -it --rm \
  -v $(pwd)/app_data:/app/app_data \
  -v $(pwd)/.env:/app/.env \
  telegram-sender

Option 4: Using installers

Download the appropriate installer from the Releases page.

• Windows: extract *-windows.zip and run install.ps1 (per-user *.tmas-backup.zip association), or run the standalone .exe without association.
• Linux: extract the *-linux.tar.gz asset and run ./install.sh (registers the app menu entry and *.tmas-backup.zip MIME type under ~/.local).
• macOS: open the .dmg (unsigned builds may need right-click → Open; Developer ID sign + notarization run in CI when Apple secrets are configured — see docs/installation.md).

Details: docs/installation.md.

Configuration

1. Get Telegram API Credentials:

• Go to my.telegram.org
• Log in with your phone number
• Go to "API development tools"
• Create a new application
• Copy the API ID and API Hash

2. Set Up Environment Variables:

 # Copy the example environment file
 cp example_files/env_template.txt .env

 # Edit .env and add your credentials
 # ⚠️ SENSITIVE: TELEGRAM_API_ID and TELEGRAM_API_HASH must be kept secret

3. Configure Application:

• Open the Settings tab
• Enter your API credentials (or they'll be loaded from .env)
• Set your preferred theme and language
• Save your settings

4. Add Your First Account:

• Go to the Accounts tab
• Click "Add Account"
• Enter your phone number
• Follow the authorization process

📖 Documentation

• Documentation Index: Complete documentation overview
• Getting Started: Orientation and required secrets
• Installation: pip, source, Docker, and frozen builds
• Quick Start Guide: Get up and running in minutes
• Usage Guide: Comprehensive user guide
• API Documentation: Complete API reference
• Configuration Guide: Environment variables and settings
• Troubleshooting: Common issues and solutions
• FAQ: Frequently asked questions
• Contributing: How to contribute to the project
• Roadmap: Future development plans

🌍 Supported Languages

• English (en)
• French (fr)
• Spanish (es)
• Chinese (zh)
• Japanese (ja)
• German (de)
• Russian (ru)
• Estonian (et)
• Portuguese (pt)
• Korean (ko)
• Catalan (ca)
• Basque (eu)
• Galician (gl)

🎨 Themes

• Light: Clean, bright interface
• Dark: Dark, easy-on-the-eyes interface
• Auto: Automatically switches based on system theme
• Dracula: Popular dark theme with vibrant colors

📋 Requirements

Minimum Requirements

• Python 3.10+
• 4GB RAM
• 1GB free disk space
• Internet connection
• Windows 10, macOS 10.15, or Linux (Ubuntu 18.04+)

Recommended Requirements

• Python 3.11+
• 8GB RAM
• 5GB free disk space
• Stable internet connection
• Windows 11, macOS 12+, or Linux (Ubuntu 20.04+)

🔧 Usage

Basic Workflow

1. Launch the Application: Run python main.py or use the installed executable
2. Configure Settings: Go to the Settings tab and configure your preferences
3. Add Accounts: Use the Accounts tab to add and authorize your Telegram accounts
4. Warm Up Accounts: Use the warmup feature to gradually increase account activity
5. Create Templates: Use the Templates tab to create message templates
6. Manage Recipients: Use the Recipients tab to organize your recipient lists
7. Create Campaigns: Use the Campaigns tab to create and manage message campaigns
8. Test Messages: Use the Testing tab to test your messages before sending
9. Monitor Logs: Use the Logs tab to monitor application and send logs

Spintax Example

Create message variations using spintax syntax:

Hello {John|Jane|Alex}, welcome to {our|my} {amazing|fantastic|great} service!

This will generate variations like:

• "Hello John, welcome to our amazing service!"
• "Hello Jane, welcome to my fantastic service!"
• "Hello Alex, welcome to our great service!"

Campaign Management

1. Create Campaign: Click "Create Campaign" in the Campaigns tab
2. Configure Settings: Set campaign name, type, and message content
3. Select Recipients: Choose recipient list or individual recipients
4. Schedule: Set start time and rate limits
5. Launch: Start, pause, or stop campaigns as needed

🛠️ Development

Setting Up Development Environment

1. Clone the Repository:

 git clone https://github.com/VoxHash/Telegram-Multi-Account-Message-Sender.git
 cd Telegram-Multi-Account-Message-Sender

2. Create Virtual Environment:

 python -m venv venv
 source venv/bin/activate  # On Windows: venv\Scripts\activate

3. Install Dependencies:

 pip install -r requirements.txt
 pip install -r requirements-dev.txt

4. Set Up Pre-commit Hooks:

 pre-commit install

5. Run Tests:

 pytest

Code Style

We use Black for code formatting and isort for import sorting:

# Format code
black app/

# Sort imports
isort app/

# Check code style
flake8 app/

# Type checking (blocking CI scope)
mypy app/core app/services app/models app/plugins \
  app/utils app/cli.py \
  app/gui/__init__.py app/gui/main.py app/gui/theme.py \
  app/gui/widgets/__init__.py app/gui/widgets/about_widget.py \
  app/gui/widgets/account_widget.py \
  app/gui/widgets/campaign_widget.py \
  app/gui/widgets/cloud_backup_widget.py \
  app/gui/widgets/dashboard_widget.py \
  app/gui/widgets/log_widget.py \
  app/gui/widgets/plugin_widget.py \
  app/gui/widgets/recipient_widget.py \
  app/gui/widgets/settings_widget.py \
  app/gui/widgets/template_widget.py \
  app/gui/widgets/testing_widget.py \
  app/gui/widgets/telegram_selector.py

Running Tests

# Run all tests
pytest

# Run with coverage
pytest --cov=app tests/

# Run specific test file
pytest tests/test_campaigns.py

🤝 Contributing

We welcome contributions! Please see our Contributing Guide for details.

How to Contribute

1. Fork the repository
2. Create a feature branch: git checkout -b feature/amazing-feature
3. Make your changes
4. Run tests: pytest
5. Commit your changes: git commit -m 'Add amazing feature'
6. Push to the branch: git push origin feature/amazing-feature
7. Open a Pull Request

Reporting Issues

Please use our Issue Templates when reporting bugs or requesting features.

📄 License

This project is licensed under the GNU General Public License v3 or later (GPL-3.0-or-later) — see the LICENSE file for details.

The desktop app is free and open source for local use. The separately developed hosted product SendGram is a private paid SaaS and is not licensed under this repository’s GPL terms. See SECURITY.md and docs/faq.md.

⚠️ Disclaimer

This application is for educational and legitimate business purposes only. Users are responsible for complying with Telegram's Terms of Service and applicable laws. The developers are not responsible for any misuse of this application.

🆘 Support

Community hub (Discussions-first): GitHub Discussions — questions, ideas, and beta tester signup. No Discord invite yet; see SUPPORT.md.

• Documentation: docs/index.md · SUPPORT.md
• Issues: GitHub Issues
• Discussions: GitHub Discussions
• Email: contact@voxhash.dev

🗺️ Roadmap

See ROADMAP.md for detailed future development plans and current project status.

📊 Statistics

• Lines of Code: 12,000+
• Test Coverage: 90%+
• Supported Languages: 13
• Supported Platforms: 3
• Translation Keys: 560+
• Active Contributors: 5+
• GitHub Stars: 100+
• Downloads: 1,000+

💖 Sponsors

We're incredibly grateful to our sponsors who help support the development and maintenance of this project!

🌟 Monthly Sponsors

• @dodierandal-arch - $100/month (Premium Sponsor) 🎉

Thank you for your generous support! Your contributions help us continue improving the project and adding new features.

Interested in becoming a sponsor? Support us on GitHub Sponsors and help make this project even better!

🏆 Acknowledgments

• Telethon - Telegram client library
• PyQt5 - GUI framework
• SQLModel - Database ORM
• Rich - Rich text and beautiful formatting
• Black - Code formatting
• isort - Import sorting
• pytest - Testing framework

📈 Changelog

See CHANGELOG.md for a list of changes and version history.

🔗 Links

• SendGram (hosted SaaS): sendgram.pro — managed cloud edition for teams
• Repository: GitHub
• Documentation: docs/index.md · SUPPORT.md
• Issues: GitHub Issues
• Discussions: GitHub Discussions (beta testers)
• Releases: GitHub Releases
• PyPI: PyPI Package

🌟 Star History

Star History Chart

---

Made with ❤️ by VoxHash