mail2telegram README

The project's README from github.com/tbxark/mail2telegram. As one markdown file: README.md.

mail2telegram


English | 中文

Receive email in Telegram: instant push notifications plus a Mini App inbox.

Deploy to Cloudflare

mail2telegram is a Telegram bot for receiving email, running entirely on Cloudflare Workers. It combines instant push notifications with a Telegram Mini App: every incoming email is pushed to your chat with quick action buttons, while the full history, attachments and every setting live in the Mini App. Mail arrives through Cloudflare Email Routing, which forwards every message to the worker, and AI summaries run on Workers AI or any OpenAI-compatible provider.

Telegram Mini App: push notification, inbox, message reader and iPad split view

How it works

Email ──▶ Telegram push with quick action buttons
      └─▶ Mini App inbox (history, attachments, settings)

All behavior is configured in the Mini App and stored in D1 — the worker itself only needs a few variables for its Telegram identity and optional API keys.

Guides

Telegram Mini App

Open the Mini App from the bot with /start. The first /start from a chat also binds the webhook and points the bot menu button at the worker, so later opens can use the menu button directly. Everything below is managed inside the Mini App:

The Mini App is protected by Telegram initData validation against TELEGRAM_TOKEN, restricted to the IDs in TELEGRAM_ID. In a plain browser the same URL asks for WEB_PASSWORD; when no password is configured, the Mini App is the only way in and the project landing page is shown instead.

On phones the app uses a native tab bar and navigation stack. On desktop clients (macOS, Telegram Desktop) and wide viewports it switches to an iPad-style split view with a sidebar, list and reading pane.

Usage

The push message structure is unchanged:

[Subject]

-----------
From : [sender]
To   : [recipient]

(Preview)(Summary)(Open)
  1. Preview shows the plain text body directly in the chat, limited to 4096 characters.
  2. Summary appears when a summary backend is enabled in Settings (Workers AI, or an OpenAI-compatible provider).
  3. Open launches the Mini App straight to this message's detail page. Telegram only allows Mini App buttons in private chats, so group notifications omit it.

Reply to any pushed message in Telegram to answer the sender through Resend.

CPU budget: parsing a message costs roughly 2ms of CPU per MB, so keep Max Size under ~2MB on the Workers free plan (10ms CPU per request). The paid plan's 30s budget has no such constraint. See Attachments.

Address lists

Rules are managed in the Mini App. A rule matches either an exact address (case-insensitive) or a regular expression. The white list takes precedence over the block list, so an allow rule can override a broad block rule for the same address.

Attachments

Attachments are stored in R2 and listed in the reader, where they can be downloaded. If no BUCKET binding is configured, mail is still stored without attachment contents.

Attachments need the whole message, so Max Size in Mail Handling has to be at least as large as the mail you want to receive. Base64 encoding adds about a third to every attachment, so budget the limit around the largest file you expect. Mail over the limit has its body truncated, and because attachments follow the body in the message, a truncated mail stores no attachments at all — the alternative would be handing you a corrupt download. The oversize policy Headers avoids the problem differently by skipping the body altogether.

Retention

Mail older than the retention setting is not part of the notification cache, but the full history remains until you delete it from the Mini App.

Development

The repo is a pnpm workspace with three packages and the deployable worker config at the root:

Path Package Contents
packages/server @mail2telegram/server Cloudflare Worker: email handlers, Telegram bot, Mini App API, D1 migrations and the Worker-runtime tests.
packages/web @mail2telegram/web Telegram Mini App (Vite + React), built to packages/web/dist/client.
packages/shared @mail2telegram/shared Types-only HTTP contract consumed by both sides; owns every type that crosses the wire. 
pnpm install
pnpm dev            # Vite dev server on :5173 + wrangler dev on :8787
pnpm build          # typecheck every package and build the Mini App into packages/web/dist/client
pnpm typecheck      # tsc --noEmit for each package
pnpm test           # pure-logic tests (tsx) + Worker-runtime tests (vitest, Miniflare)
pnpm test:unit      # mergeSettings / testAddress / parseEmail only
pnpm test:pool      # D1, inbound-email and cleanup tests in the Workers runtime
pnpm lint           # oxlint
pnpm lint:fix       # oxlint --fix
pnpm format         # oxfmt
pnpm format:check   # oxfmt --check (used by CI)
pnpm screenshots    # regenerate the README images in docs/assets from mock data

wrangler dev serves the built packages/web/dist/client, so run pnpm build (or keep pnpm build:web running) at least once before starting it; pnpm dev runs both processes but does not build the assets.

Local D1 migrations:

pnpm db:migrate:local

The Mini App normally requires a valid Telegram initData signature. For local development, put WEB_PASSWORD=dev (plus your bot values) in the gitignored .dev.vars, run wrangler dev and open http://localhost:5173, then sign in with that password — exactly how a browser session works in production. The ?debug flag still mocks the Telegram UI (theme, viewport, platform) for previewing, and ?platform=ios previews the phone layout in a desktop browser. Never set a real WEB_PASSWORD in anything but the deployed worker's variables.

License

mail2telegram is released under the MIT license. See LICENSE for details.

mail2telegram (tbxark/mail2telegram)

Searching Database…

905 ·GitHub
Mail2telegram
Что это?mail2telegram — Telegram-бот, принимающий вашу почту и работающий целиком на Cloudflare Workers, сочетающий мгновенные пуш-уведомления в чате с ящиком в виде Telegram Mini App для истории, вложений и настроек.
Это отдельный сервер или он работает целиком на бессерверной платформе Cloudflare?Он полностью serverless: бот, API Mini App и хранилище работают на Cloudflare Workers с D1 для данных и R2 для вложений, так что управлять сервером не нужно.
Как задеплоить mail2telegram?Нажмите кнопку «Deploy to Cloudflare», которая клонирует репозиторий, создаёт ресурсы D1 и R2, запрашивает данные вашего Telegram-бота и деплоит; после этого вы привязываете бота и настраиваете Cloudflare Email Routing. Ручной путь через CLI, GitHub Actions или Workers Builds тоже задокументирован.
Что мне нужно перед настройкой?Аккаунт Cloudflare с Workers, D1 и R2, токен Telegram-бота и настроенный Cloudflare Email Routing, пересылающий почту на воркер; для AI-сводок дополнительно нужны Workers AI или OpenAI-совместимый API-ключ.
Есть ли ограничение на размер получаемых писем?Да — парсинг стоит около 2 мс CPU на МБ, так что на бесплатном плане Workers (бюджет 10 мс CPU) нужно держать Max Size примерно ниже 2 МБ; бюджет платного плана в 30 секунд снимает это ограничение. У слишком больших писем тело обрезается, а вложения теряются полностью.
Mini App выглядит одинаково на телефоне и на компьютере?Нет — на телефонах он использует нативную панель вкладок и стек навигации, а в десктопных клиентах Telegram и при широких вьюпортах переключается на раздельный вид в стиле iPad с сайдбаром, списком и панелью чтения.
Кто может открыть Mini App и увидеть мою почту?Mini App проверяет initData Telegram по токену вашего бота и пускает только chat ID, перечисленные в TELEGRAMID; открытие того же URL из обычного браузера, наоборот, требует WEBPASSWORD, а если он не задан, вместо ящика показывается посадочная страница проекта.
Можно ли отвечать на письма прямо из Telegram?Да, ответьте на любое пришедшее сообщение в Telegram, и mail2telegram отправит ваш ответ первоначальному отправителю через Resend.
Что происходит со старыми письмами?Письма старше настройки хранения выпадают из кэша уведомлений, но полная история остаётся в Mini App, пока вы сами её не удалите.
Можно ли фильтровать, чьи письма доходят до меня?Да, в Mini App можно задать белые и чёрные списки с сопоставлением по точному адресу или регулярному выражению, причём правила белого списка имеют приоритет над блокирующими для того же адреса.
What are similar projects?cloudflare_temp_email, DoulorCloud, mailflare, cloud-mail, ResolveHQ, nodewarden, novu, open-compute
Which topics is it in?cloudflare-r2, cloudflare-d1, push-notifications, telegram-bot, pnpm, cloudflare-workers, serverless, notifications, email, cloudflare, telegram, monorepo
Creator
tbxark
Size
3.6 MB
Stars
905
Updated
CommitSep 25Release2.0.0Sep 15
Age
3y
Commits · 90 Days