kchwr/tg2smtp repository overview

⁠Telegram to SMTP

A Telegram Bot that forwards chat massages and files as emails. Works in private chats, groups and channels.

This bot is only capable of forwarding text messages, polls, locations, photos, documents, audio files, video files, voice messages, stickers and video notes.

⁠Use Case

Some of our club members refuse to join the club's private information broadcast Telegram channel. The organizer had to write each message twice. One for Telegram and one for email distribution. This bot fixes the problem by simply sending Telegram messages to a mailing list.

⁠Installation

⁠Instructions

1. Create a new Telegram Bot using the official Telegram BotFather⁠ and note the Bot's username and HTTP API Token.
2. Invite your new Bot into the chat of your choice. Your Bot must have just enough permissions to read chat messages.
3. Retrieve the ID of the current chat.
   1. Send any message to the Telegram chat (or group or channel)
   2. Open https://q3qkk.csb.app/⁠ and paste the Bot's token into the input field

The tool extracts the chat ID from the returned JSON response. Note down your chat ID.

Alternatively, if you don't want to use an untrusted tool, you can visit https://api.telegram.org/bot${token}/getUpdates and replace ${token} with your HTTP API Token. Find the number where it reads [...]"chat":{"id":>someNumber< or

{
  "ok": true,
  "result": [
    {
      [...],
      "message": {
        [...],
        "chat": {
          "id": >someNumber<, ← that is the number you want
          [...]
        },
        [...]
      }
    }
  ]
}

⁠Deployment

The Telegram Bot you have created is just a gateway between Telegram and the actual Service Tg2SMTP. You must start this service in order to retrieve messages and send emails. You'll probably want to run Tg2SMTP on a server either way to guarantee mails get sent instantly.

⁠Configuration

Before you can start you should know your SMTP provider's hostname/server address/SMTP server, port and authentication mechanisms and constraints as well as your login credentials. Most providers provide a FAQ for common email clients like Outlook, Thunderbird etc.

The following table shows all available configuration properties. Choose either Property or Environment Variable column depending on your deployment method. Spring, the underlying framework, allows a deployment method independent way to provide configuration for Tg2SMTP. To do this, write the desired configuration key-value pairs in an application.properties or application.yml file and place the file next to the .jar file. Spring then reads this file at startup.

Both profiles, smtp_auth and smtp_tls, are active per default, as it is the most common authentication mechanism throughout.

⁠Message Types

This bot will only forward these messages as stated in the introduction. For the sake of completeness the following list shows the available messages types and their activation key.

⁠Docker

Replace the sample configuration and run the command below to start a Tg2SMTP Docker Container.

docker run -d \
 -e TG2SMTP_MAIL_SUBJECT="[Telegram] New message" \
 -e [email protected],[email protected] \
 -e TG2SMTP_CHAT_ID=1337420 \
 -e TG2SMTP_BOT_USERNAME=MyAwesoneTg2SmtpBot \
 -e TG2SMTP_BOT_TOKEN=XXXXXXXX:YYYYYYYYY \
 -e MAIL_HOST=smtp.example.com \
 -e MAIL_PORT=587 \
 -e [email protected] \
 -e MAIL_PASSWORD=s3cr3t \
 -e MAIL_HELO=my-host.example.com \
 -e [email protected] \
 -e [email protected] \
 -e SPRING_PROFILES_ACTIVE=smtp_auth,smtp_tls \
 kchwr/tg2smtp:latest

Docker Swarm Mode users may configure their stack using Docker Secrets. Just append _FILE to the appropriate environment variables: MAIL_USER_FILE, MAIL_PASSWORD_FILE, TG2SMTP_MAIL_TO_FILE, TG2SMTP_CHAT_ID_FILE, TG2SMTP_BOT_USERNAME_FILE, TG2SMTP_BOT_TOKEN_FILE. Keep in mind that only one Tg2SMTP instance with the same username can register at the Telegram Bot API concurrently.

⁠Licence

Apache License 2.0 - Kammerchor Wernigerode e.V.⁠ - Built with :heart:

⁠Footnotes

1. Use ALL to forward all compatible messages or select the type of message you want. ↩⁠

2. Depends on the provider if the HELO header is necessary, but might resolve issues anyway if set ↩⁠