A Telegram bot that allows users to scrape web articles from any website, convert them to Kindle-compatible EPUB files, and send them directly to their Kindle devices via email. Substack articles are specially optimized for the best reading experience.
You can try the bot immediately without any setup at: @SubstackKindleBot
Or deploy your own instance using the instructions below.
- Visit @SubstackKindleBot on Telegram
- Send
/startto begin - Configure your Kindle email with
/config - Send any article URL to convert and receive on your Kindle
git clone https://github.com/gunneone/web-to-kindle-telegram-bot.git
cd web-to-kindle-telegram-bot
pip install -r requirements.txt
python cli.py https://your-article-urlFollow the full installation instructions below.
- Multiple interfaces: Use via Telegram bot or command-line interface (CLI)
- Web scraper to extract content from any website article, with special optimizations for Substack articles that remove unnecessary elements like buttons and ads.
- Converts extracted content to an EPUB format compatible with Kindle devices.
- Integrates with a Telegram bot for an intuitive user interface.
- Sends the EPUB file to the user's Kindle email address.
- Allows configuration of Kindle email within the bot.
- Configurable image link preservation: Toggle whether to preserve clickable links on images (useful for zoom functionality).
- Automatic file cleanup: Monitors disk space and automatically deletes old HTML and EPUB files when space is low (below 2GB) to prevent storage issues while keeping recent files for debugging.
- Python 3.12 or higher
- SMTP server access: Required to send emails to Kindle devices.
- Telegram Bot Token: Obtain from the Telegram BotFather.
-
Clone the Repository:
git clone https://github.com/gunneone/web-to-kindle-telegram-bot.git cd web-to-kindle-telegram-bot -
Set Up the Python Environment:
Use
pyenvto ensure you're using the correct Python version.pyenv install 3.12.11 pyenv local 3.12.11 pip install -r requirements.txt -
Configuration:
Copy the example
.envfile and fill in your configuration.cp .env.example .env
Populate
.envwith:# Telegram Bot Token TELEGRAM_TOKEN=YOUR:BOT_TOKEN # Email configuration EMAIL_FROM=your@email.domain EMAIL_PASSWORD=your-email-password # SMTP configuration SMTP_HOST=your_smtp_server SMTP_PORT=587
-
Run the Bot:
Option A: Direct Python execution
python telegram_bot.py
Option B: Using Docker Compose (Recommended for production)
docker compose up -d
This will start both the Telegram bot and the disk monitoring service that automatically manages old files to prevent storage issues.
Use /start to initialize the bot and view a welcome message.
Use /config to set or update your Kindle email. You will be prompted to input an email address ending in @kindle.com.
Use /settings to view your current configuration, including:
- Kindle email address
- Image link preservation setting
Use /imagelinks to toggle whether clickable links on images are preserved in the EPUB. When enabled, you can click on images to zoom or view full resolution versions.
Use /send followed by any web article URL to send content directly to your Kindle. Alternatively:
- Send
/sendwithout an URL, and the bot will prompt you to provide a link.
Add EMAIL_FROM (as set in .env) to your approved senders list at Amazon Kindle Settings.
-
Scraping Content:
- The
web_scraper.pyextracts the main content, title, and author from web articles. For Substack articles, it provides enhanced extraction with removal of unnecessary buttons and ads.
- The
-
Converting to EPUB:
- In
epub_converter.py, the content is packaged into an EPUB book, embedding metadata like the title, author, and images.
- In
-
Sending Emails:
- The
email_sender.pysends the generated EPUB to the user's Kindle email via an SMTP server.
- The
-
Telegram Interface:
- Users interact with the bot using straightforward commands to configure their Kindle email, toggle settings, and process articles from any website.
-
Automatic File Management:
- The
disk_monitor.pyservice continuously monitors disk space and automatically removes the oldest HTML and EPUB files when available space falls below 2GB, ensuring the system doesn't run out of storage while preserving recent files for debugging purposes.
- The
/start- Initialize the bot and view welcome message/config- Configure or update your Kindle email address/settings- View all current settings (email, image link preservation)/imagelinks- Toggle image link preservation on/off/cancel- Cancel current operation
For users who prefer command-line tools or want to integrate the functionality into scripts, a CLI tool is available:
# Install dependencies
pip install -r requirements.txt
# Process any web article (basic usage)
python cli.py https://example.com/article-title
# Process article with image links preserved (clickable images)
python cli.py --preserve-image-links https://example.com/article-title- Direct processing: Convert web articles to EPUB without needing a Telegram bot (supports any website, with special optimizations for Substack)
- Image link preservation: Use
--preserve-image-linksflag to keep clickable links on images - Batch processing capability: Can be integrated into scripts for multiple articles
- Email integration: Automatically sends EPUB to configured Kindle email
The CLI tool also supports the preserve image links feature:
# Process article with image links preserved
python cli.py --preserve-image-links https://example.com/article
# Process article with image links removed (default)
python cli.py https://example.com/article- Kindle Compatibility: The EPUB files are optimized for Kindle devices. Some features might not work on other platforms.
The following packages are used in this project:
- requests: HTTP requests for web scraping.
- beautifulsoup4: HTML parsing for scraping articles.
- EbookLib: For creating EPUB files.
- python-telegram-bot: Telegram API integration.
- python-dotenv: Managing environment variables.
- SQLAlchemy: Database management using SQLite.
- click: Command-line interface framework.
- readability-lxml: Content extraction and readability improvements.
- validators: URL and data validation.
Install dependencies via:
pip install -r requirements.txtFor support, please open an issue in the repository.