Forward Email Alerts to Telegram Instantly with smtp_to_telegram

A lightweight SMTP server that forwards all incoming emails directly to Telegram — ideal for real-time alerts, automation, and developer workflows.

When managing servers, CI/CD pipelines, or automated scripts, getting critical notifications instantly can save time, effort, and even prevent disasters. While most tools rely on email for alerts, setting up email servers or monitoring inboxes can be overkill.

That’s where smtp_to_telegram comes in — a minimalist, open-source SMTP server written in Go that forwards all incoming email messages straight to one or more Telegram chats via a bot.

Why Use smtp_to_telegram?

• 🚀 Instant notifications in your Telegram app, no email clients needed.
• 🔧 Works with any software that sends email — from cron jobs to backup scripts.
• 🔐 No need to expose credentials, use TLS, or set up mail servers.
• 🐳 Docker-ready and easy to deploy in minutes.
• ✅ MIT-licensed and fully open-source.

Common Use Cases

• Backup completion alerts
• Cron job success/failure messages
• Zabbix or Prometheus notifications (without webhook setup)
• CI/CD pipeline status
• Web form submissions or logs from custom apps

Getting Started in 5 Steps

1. Create a Telegram bot
   Talk to @BotFather, create a bot, and save the BOT_TOKEN.
2. Start a chat with your bot
   Open the bot in your Telegram app and send /start to activate it.
3. Retrieve your chat ID
   Use the following command and look for chat.id in the JSON: curl https://api.telegram.org/bot<BOT_TOKEN>/getUpdates
4. Run the Docker container
   Replace the variables with your own: docker run --name smtp_to_telegram \ -e ST_TELEGRAM_CHAT_IDS=<CHAT_ID1>,<CHAT_ID2> \ -e ST_TELEGRAM_BOT_TOKEN=<BOT_TOKEN> \ -p 2525:2525 \ kostyaesmukov/smtp_to_telegram
5. Point your software to smtp_to_telegram:2525
   • No TLS or auth required
   • Just configure the SMTP server as smtp_to_telegram and port 2525 in your sender software

Message Format Customization

By default, messages look like this:

From: someone@example.com
To: admin@myserver.com
Subject: Backup Complete

Your backup completed successfully!

Want to simplify it? Set your own format:

-e ST_TELEGRAM_MESSAGE_TEMPLATE="Subject: {subject}\n\n{body}"

Available placeholders:

• {from}, {to}, {subject}, {body}, {attachments_details}

Docker + Local Networking

If you’re using Docker Compose or internal Docker networking, you can route other containers’ SMTP traffic to smtp_to_telegram using the container name:

services:
  app:
    environment:
      MAIL_HOST: smtp_to_telegram
      MAIL_PORT: 2525
  smtp_to_telegram:
    image: kostyaesmukov/smtp_to_telegram
    ports:
      - 2525:2525
    environment:
      ST_TELEGRAM_CHAT_IDS: "<CHAT_ID>"
      ST_TELEGRAM_BOT_TOKEN: "<BOT_TOKEN>"

Advantages

• ✅ Tiny footprint, runs in seconds
• 🔒 Ideal for private networks or local alerts
• 📱 Real-time push to mobile devices
• 🔄 No dependencies on third-party email providers
• 🧩 No CAPTCHA, no spam filters, no delay

Limitations

• No retry if Telegram is unreachable (though recent updates improve reliability)
• No TLS or encryption — use only inside trusted networks
• Doesn’t support receiving emails with attachments (yet)

Final Thoughts

smtp_to_telegram is a fantastic example of doing one thing and doing it well. If you’re tired of managing email notifications or just want a faster way to receive alerts on your phone, give it a spin. In a world full of bloated monitoring tools, sometimes a simple SMTP bridge is all you need.