{"id":28816157,"url":"https://github.com/whoisgray/cloudmail-to-telegram","last_synced_at":"2026-05-17T00:35:42.723Z","repository":{"id":298955841,"uuid":"1001663409","full_name":"WhoisGray/cloudmail-to-telegram","owner":"WhoisGray","description":"🚀 Professional email forwarding service that intelligently processes emails and forwards them to Telegram with smart parsing, rich formatting, and enterprise-grade security features.","archived":false,"fork":false,"pushed_at":"2025-06-13T19:36:04.000Z","size":14,"stargazers_count":2,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-07-24T16:53:20.104Z","etag":null,"topics":["automation","cloudflare","cloudflare-workers","email-forwarding","email-parsing","email-routing","javascript","serverless","telegram-bot","telegram-integration"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","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/WhoisGray.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,"zenodo":null}},"created_at":"2025-06-13T19:21:44.000Z","updated_at":"2025-07-23T12:37:46.000Z","dependencies_parsed_at":"2025-06-13T20:44:06.122Z","dependency_job_id":null,"html_url":"https://github.com/WhoisGray/cloudmail-to-telegram","commit_stats":null,"previous_names":["whoisgray/cloudmail-to-telegram"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/WhoisGray/cloudmail-to-telegram","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/WhoisGray%2Fcloudmail-to-telegram","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/WhoisGray%2Fcloudmail-to-telegram/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/WhoisGray%2Fcloudmail-to-telegram/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/WhoisGray%2Fcloudmail-to-telegram/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/WhoisGray","download_url":"https://codeload.github.com/WhoisGray/cloudmail-to-telegram/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/WhoisGray%2Fcloudmail-to-telegram/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":276679150,"owners_count":25684869,"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","status":"online","status_checked_at":"2025-09-24T02:00:09.776Z","response_time":97,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"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":["automation","cloudflare","cloudflare-workers","email-forwarding","email-parsing","email-routing","javascript","serverless","telegram-bot","telegram-integration"],"created_at":"2025-06-18T17:02:30.265Z","updated_at":"2025-09-24T02:20:21.621Z","avatar_url":"https://github.com/WhoisGray.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# 📧 CloudMail-to-Telegram\n\n[![Deploy to Cloudflare Workers](https://deploy.workers.cloudflare.com/button)](https://deploy.workers.cloudflare.com/?url=https://github.com/WhoisGray/cloudmail-to-telegram)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n[![Cloudflare Workers](https://img.shields.io/badge/Cloudflare-Workers-orange)](https://workers.cloudflare.com/)\n\n\u003e 🚀 **Professional email forwarding service** that intelligently processes incoming emails and forwards them to Telegram with proper formatting, smart parsing, and comprehensive error handling.\n\n## ✨ Features\n\n### 🎯 **Smart Email Processing**\n\n- **Multi-format support**: Handles plain text, HTML, and multipart emails\n- **Encoding detection**: Automatically decodes base64 and quoted-printable content\n- **Content prioritization**: Intelligently selects the best readable content\n- **Unicode support**: Proper UTF-8 handling for international emails\n\n### 📱 **Telegram Integration**\n\n- **Three-tier delivery**: Metadata → Body preview → Full attachment\n- **Rich formatting**: Beautiful MarkdownV2 messages with emojis\n- **File attachments**: Complete email content as downloadable .txt files\n- **Error notifications**: Real-time alerts for processing failures\n\n### 🛡️ **Enterprise-Grade Security**\n\n- **Rate limiting**: Prevents spam and abuse (10 emails/minute per sender)\n- **Input validation**: Comprehensive safety checks\n- **Error handling**: Graceful failure recovery\n- **Configuration validation**: Startup safety checks\n\n### ⚡ **Performance \u0026 Reliability**\n\n- **Retry logic**: Automatic retry with exponential backoff\n- **Stream processing**: Memory-efficient email handling\n- **Health monitoring**: Built-in health check endpoint\n- **Detailed logging**: Comprehensive error tracking\n\n## 🚀 Quick Setup\n\n### 1. Prerequisites\n\n- [Cloudflare account](https://cloudflare.com) with Workers plan\n- [Telegram Bot Token](https://t.me/BotFather) from BotFather\n- Telegram Channel ID where emails will be forwarded\n\n### 2. Get Your Telegram Credentials\n\n#### Create a Bot:\n\n1. Message [@BotFather](https://t.me/BotFather) on Telegram\n2. Send `/newbot` and follow the instructions\n3. Save your bot token (format: `123456789:ABCdefGHIjklMN-OpqRSTuvwXYZ`)\n\n#### Get Channel ID:\n\n1. Add your bot to your channel as an administrator\n2. Send a test message to your channel\n3. Visit: `https://api.telegram.org/bot\u003cYOUR_BOT_TOKEN\u003e/getUpdates`\n4. Find your channel ID in the response (format: `@yourchannel` or `-1001234567890`)\n\n### 3. Deploy to Cloudflare Workers\n\n#### Option A: One-Click Deploy\n\n[![Deploy to Cloudflare Workers](https://deploy.workers.cloudflare.com/button)](https://deploy.workers.cloudflare.com/?url=https://github.com/WhoisGray/cloudmail-to-telegram)\n\n#### Option B: Manual Deploy\n\n```bash\n# Clone the repository\ngit clone https://github.com/WhoisGray/cloudmail-to-telegram.git\ncd cloudmail-to-telegram\n\n# Install Wrangler CLI (if not already installed)\nnpm install -g wrangler\n\n# Login to Cloudflare\nwrangler auth login\n\n# Configure your worker\ncp wrangler.toml.example wrangler.toml\n# Edit wrangler.toml with your account details\n\n# Set environment variables\nwrangler secret put TELEGRAM_BOT_TOKEN\nwrangler secret put TELEGRAM_CHANNEL_ID\n\n# Deploy\nwrangler deploy\n```\n\n### 4. Configure Email Routing\n\n1. Go to your Cloudflare dashboard\n2. Navigate to **Email** → **Email Routing**\n3. Add your domain and verify DNS records\n4. Create a new route:\n   - **Address**: `*@yourdomain.com` (or specific addresses)\n   - **Action**: Send to Worker\n   - **Worker**: Select your deployed worker\n\n## ⚙️ Configuration\n\n### Environment Variables\n\n| Variable              | Description                            | Example                          |\n| --------------------- | -------------------------------------- | -------------------------------- |\n| `TELEGRAM_BOT_TOKEN`  | Your Telegram bot token from BotFather | `123456789:ABCdef...`            |\n| `TELEGRAM_CHANNEL_ID` | Your Telegram channel ID               | `@mychannel` or `-1001234567890` |\n\n### Advanced Configuration\n\nThe worker includes several configuration constants you can modify:\n\n```javascript\nconst CONFIG = {\n  MAX_BODY_LENGTH: 4000, // Maximum body preview length\n  MAX_SUBJECT_LENGTH: 100, // Maximum subject length in notifications\n  TELEGRAM_MESSAGE_LIMIT: 4096, // Telegram's message limit\n  RATE_LIMIT_WINDOW: 60000, // Rate limiting window (1 minute)\n  MAX_EMAILS_PER_WINDOW: 10, // Max emails per sender per window\n};\n```\n\n## 📋 How It Works\n\nWhen an email arrives, the worker:\n\n1. **🔍 Validates** the configuration and checks rate limits\n2. **📊 Extracts** metadata (from, to, subject, date, message-id)\n3. **🧠 Parses** the email content intelligently:\n   - Detects multipart structure\n   - Prioritizes text/plain over text/html\n   - Decodes base64 and quoted-printable content\n   - Handles various character encodings\n4. **📤 Sends three Telegram messages**:\n   - **Metadata message**: Sender, recipient, subject, etc.\n   - **Body preview**: Clean, readable email content\n   - **Full attachment**: Complete raw email as .txt file\n\n## 📱 Telegram Output Example\n\n```\n📧 New Email Received\n\nFrom: john@example.com\nTo: support@mydomain.com\nSubject: Question about your service\nDate: 2025-01-15T10:30:00Z\nContent Type: text/plain\nMessage ID: abc123@example.com\n```\n\n```\n📄 Email Content:\n\nHello,\n\nI have a question about your service...\n```\n\n```\n📎 Full email content: \"Question about your service\"\n[email-abc123@example.com-2025-01-15.txt]\n```\n\n## 🔧 API Endpoints\n\n### Health Check\n\n```\nGET https://your-worker.your-subdomain.workers.dev/health\n```\n\nReturns:\n\n```json\n{\n  \"status\": \"healthy\",\n  \"version\": \"2.0.0\",\n  \"timestamp\": \"2025-01-15T10:30:00.000Z\"\n}\n```\n\n## 🛠️ Development\n\n### Local Development\n\n```bash\n# Install dependencies\nnpm install\n\n# Start local development server\nwrangler dev\n\n# Run tests\nnpm test\n```\n\n### Testing Email Processing\n\n```bash\n# Send test email (requires configured email routing)\ncurl -X POST \"https://your-worker.workers.dev\" \\\n  -H \"Content-Type: text/plain\" \\\n  -d \"Test email content\"\n```\n\n## 🔒 Security Features\n\n- **Rate Limiting**: Prevents spam attacks (configurable limits)\n- **Input Validation**: Sanitizes all email content\n- **Error Handling**: Graceful failure without exposing sensitive data\n- **Markdown Escaping**: Prevents Telegram formatting injection\n- **Content Size Limits**: Prevents oversized message failures\n\n## 🚨 Troubleshooting\n\n### Common Issues\n\n#### ❌ \"Configuration error\"\n\n- **Cause**: Missing or invalid environment variables\n- **Solution**: Verify `TELEGRAM_BOT_TOKEN` and `TELEGRAM_CHANNEL_ID` are set correctly\n\n#### ❌ \"Rate limit exceeded\"\n\n- **Cause**: Too many emails from the same sender\n- **Solution**: Adjust rate limiting in configuration or wait for the window to reset\n\n#### ❌ \"Failed to send to Telegram\"\n\n- **Cause**: Invalid bot token or channel permissions\n- **Solution**: Ensure bot is added as admin to the channel\n\n#### ❌ \"Processing failed\"\n\n- **Cause**: Malformed email or parsing error\n- **Solution**: Check worker logs in Cloudflare dashboard\n\n### Debug Mode\n\nSet `DEBUG=true` in environment variables for verbose logging.\n\n## 📊 Monitoring\n\nMonitor your worker's performance:\n\n1. **Cloudflare Dashboard**: View metrics, logs, and errors\n2. **Health Endpoint**: Automated monitoring with `/health`\n3. **Telegram Notifications**: Error alerts sent directly to your channel\n\n## 🤝 Contributing\n\nContributions are welcome! Please feel free to submit a Pull Request.\n\n### Development Setup\n\n1. Fork the repository\n2. Create a feature branch\n3. Make your changes\n4. Add tests if applicable\n5. Submit a pull request\n\n## 📄 License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n\n## 🙏 Acknowledgments\n\n- Built with [Cloudflare Workers](https://workers.cloudflare.com/)\n- Email parsing inspired by modern email standards\n- Telegram integration using [Bot API](https://core.telegram.org/bots/api)\n\n## 💬 Support\n\n- 🐛 **Bug Reports**: [GitHub Issues](https://github.com/WhoisGray/cloudmail-to-telegram/issues)\n- 💡 **Feature Requests**: [GitHub Discussions](https://github.com/WhoisGray/cloudmail-to-telegram/discussions)\n\n---\n\n\u003cdiv align=\"center\"\u003e\n  \u003cp\u003eMade with ❤️ by \u003ca href=\"https://github.com/WhoisGray\"\u003eWhoisGray\u003c/a\u003e\u003c/p\u003e\n  \u003cp\u003e⭐ Star this repo if it helped you!\u003c/p\u003e\n\u003c/div\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwhoisgray%2Fcloudmail-to-telegram","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fwhoisgray%2Fcloudmail-to-telegram","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwhoisgray%2Fcloudmail-to-telegram/lists"}