mail2telegram cloudflare email routing
/mail2telegram
mail2telegram does exactly one thing well: it converts incoming emails into Telegram notifications without you running a mail server. For developers already inside the Cloudflare ecosystem, the setup friction is low and the free tier covers most personal use cases. The catch is that it trades a traditional mail client for a Cloudflare dependency, and the no-attachments limitation means attachments still need a separate forwarding path.
What is mail2telegram
mail2telegram is a Cloudflare Worker that receives emails via Cloudflare Email Routing and pushes them as formatted messages to a Telegram bot. Each email becomes a Telegram message with inline buttons to preview text, view full content in a browser, or read an AI-generated summary. The worker stores inbox state and filter rules in a KV namespace you bind yourself.
Key features of mail2telegram
- โEmail routing via Cloudflare Workers โ no dedicated server or mail software required
- โInline Telegram buttons: Preview, Summary (AI), Text, and HTML view modes
- โDisposable inbox creation with any recipient prefix, managed through the bot
- โSender whitelist/blacklist managed via a built-in Telegram mini-app
- โAI email summarization using Workers AI or a custom OpenAI API key
- โKV-backed storage for inbox state, filter rules, and email cache with configurable TTL
- โGuardian Mode to suppress duplicate notifications from Worker retries
- โOptional email backup forwarding to a personal address via FORWARD_LIST
Practical use cases for mail2telegram
- โขMonitoring transactional emails โ order confirmations, shipping updates, password resets โ without a full mail client open
- โขCreating throwaway inbox addresses on the fly for services you don't fully trust, read directly from Telegram
- โขLightweight email automation: filter by sender regex and receive only the notifications you care about, discarding the rest silently
- โขSpam triage at the gateway level โ use whitelist rules to auto-forward only known senders and block the rest server-side before they hit your device
Deploying mail2telegram to Cloudflare Workers
Deploying requires a Cloudflare account with Email Routing enabled, a Telegram bot token from @BotFather, and a KV namespace to bind. Clone the repo, copy `wrangler.example.jsonc` to `wrangler.jsonc` with your credentials, then run `yarn pub`. After deployment, call your worker URL at `/init` to bind the Telegram webhook. Cloudflare's free Workers tier handles moderate personal use without billing. Both CLI deployment and a copy-paste path for precompiled code are documented.
Using the bot after deployment
After binding Cloudflare Email Routing to forward all emails to your worker, incoming mail triggers a Telegram message with subject, sender, recipient, and four action buttons. The Preview button shows plain text up to 4096 characters directly in chat. Summary generates a short AI digest using Workers AI or your OpenAI key. Text opens a web page for longer emails, and HTML renders rich-text emails with a warning about tracking scripts. The Telegram mini-app manages whitelist and blacklist rules without touching environment variables. Emails expire from the cache after MAIL_TTL seconds for security.
Strengths
- โRuns on Cloudflare Workers โ zero infrastructure to maintain, free tier is generous for personal use
- โTypeScript codebase is readable and deploys in minutes via wrangler
- โBuilt-in mini-app handles sender filtering without editing environment variables
- โMulti-ID support: one worker can notify multiple Telegram accounts, useful for shared inboxes
- โConfigurable max email size and truncation policy to prevent worker timeouts on large messages
- โAI summarization without mandatory API key if you bind Cloudflare Workers AI
Known limitations of mail2telegram
- โณNo attachment support โ the README explicitly acknowledges this and points to a separate project (testmail-viewer) for attachment forwarding
- โณThe entire workflow depends on Cloudflare Email Routing and Workers reliability, so an outage on either service breaks message delivery.
- โณGuardian Mode (duplicate suppression) consumes extra KV writes, which has both cost and rate-limit implications at scale
- โณUsing the Telegram mini-app requires setting a public privacy policy via @BotFather, which may not suit enterprise environments
- โณNo native reply-to-email functionality without binding Resend and providing an API key
Alternatives to mail2telegram
Frequently asked questions
mail2telegram itself is MIT-licensed and costs nothing. You only pay for Cloudflare Workers usage, which fits within the free tier for typical personal inboxes.
No. The README acknowledges this explicitly. Attachments must be forwarded to a separate service like the author's testmail-viewer using the FORWARD_LIST environment variable.
Visit your worker URL at the /init endpoint once โ for example, https://project_name.user_name.workers.dev/init. The response confirms whether the Telegram webhook bound successfully.
Guardian Mode tracks the state of each email notification in KV storage to detect and suppress retries. It reduces duplicate messages caused by Cloudflare Worker timeouts, but it increases KV write usage.
Yes. Set the OPENAI_API_KEY environment variable and the bot will generate AI summaries without requiring Cloudflare Workers AI.
Cloudflare Workers may retry timed-out emails, sending duplicate notifications. mail2telegram offers two defenses: a backup email in FORWARD_LIST preserves messages server-side, and optional Guardian Mode tracks state in KV to suppress retries locally.
The problem it solves
Getting email notifications on the go usually means running a full mail client, configuring IMAP/SMTP, or paying for a forwarding service. Temporary or disposable email workflows are even messier, often requiring third-party services with rate limits or accounts to manage.
Who should try it โ and who should skip
Developers already using Cloudflare Pages or Workers who want email-to-Telegram notifications without running a mail server will find the setup worthwhile. It is particularly useful for monitoring transactional emails and creating disposable addresses on the fly. If you need attachment support, strict data-residency controls, or want to avoid Cloudflare vendor lock-in entirely, look elsewhere โ or at least budget time to route attachments separately.
Related repositories
Want a second opinion on mail2telegram?
Ask an AI that can read this page โ one click and you get its take on mail2telegram.