HelloGitHub Email Configuration Options for the Notification System

The HelloGitHub notification system uses a simple SMTP-based configuration defined by the MAIL dictionary and RECEIVERS list in script/github_bot/github_bot.py to send automated email alerts.

The 521xueweihan/HelloGitHub repository includes an automated GitHub bot that monitors trending repositories and delivers updates via email. Understanding the available email configuration options for the notification system enables you to customize sender credentials, SMTP server parameters, and recipient lists to integrate with your existing mail infrastructure.

Core Email Configuration Parameters

The email functionality is controlled by a Python dictionary named MAIL located in script/github_bot/github_bot.py. This configuration object supports standard SMTP authentication and connection parameters required to send notifications via external mail servers.

Sender Authentication

The following keys manage the identity and credentials used to authenticate with the SMTP server:

• mail: The sender email address that appears in the "From" field of outgoing messages. This is typically the same as the username for authentication purposes.
• username: The SMTP login username. In most configurations, this matches the mail value, though some enterprise servers may require a distinct authentication identity.
• password: The SMTP login password or application-specific authorization token. For services like QQ Mail or Gmail, this should be an app-specific password rather than your main account password.

SMTP Server Settings

Connection parameters define which mail server handles the delivery:

• host: The SMTP server hostname. The reference implementation uses QQ Mail (smtp.qq.com), but you can substitute any valid SMTP endpoint such as smtp.gmail.com or your organization's internal mail gateway.
• port: The SMTP server port. The configuration defaults to 465, which enables SSL/TLS encryption via SMTP_SSL. Alternative ports like 587 for STARTTLS would require modifying the connection logic in the send_email function.

Configuring Recipients with RECEIVERS

Separate from the MAIL configuration, the system uses a global list named RECEIVERS to define who receives the notifications. This list contains one or more email addresses as Python strings.

You can configure multiple recipients to distribute notifications across a team:

RECEIVERS = [
    'admin@example.com',
    'devops@example.com',
    'alerts@example.com'
]

The send_email function iterates through this list and delivers the same HTML content to each address using individual SMTP transactions.

Implementation Details in github_bot.py

The actual email transmission logic resides in the send_email function (lines 86-108 of script/github_bot/github_bot.py). This function constructs a multipart HTML message and establishes an encrypted connection using Python's smtplib.SMTP_SSL.

The implementation follows this workflow:

1. Parse the MAIL dictionary to extract credentials and server settings
2. Create a MIMEText object containing the HTML notification content
3. Connect to the specified host and port using SMTP_SSL for encryption
4. Authenticate with the username and password
5. Iterate through RECEIVERS and call sendmail for each recipient

This design ensures that credentials are centralized in the MAIL configuration while allowing flexible recipient management through the RECEIVERS list.

Practical Configuration Examples

Basic MAIL Configuration

To configure the bot for a standard QQ Mail account, modify the MAIL dictionary in script/github_bot/github_bot.py:

MAIL = {
    'mail': 'mybot@qq.com',           # sender address

    'username': 'mybot@qq.com',        # SMTP user

    'password': 'abcdefghijklmnop',    # QQ Mail app-specific token

    'host': 'smtp.qq.com',             # QQ Mail SMTP server

    'port': 465                        # SSL port

}

RECEIVERS = [
    'admin@example.com'
]

Environment Variable Configuration

For production deployments, avoid hardcoding credentials by using environment variables:

import os

MAIL = {
    'mail': os.getenv('MAIL_ADDRESS', ''),
    'username': os.getenv('MAIL_USER', ''),
    'password': os.getenv('MAIL_PASS', ''),
    'host': os.getenv('MAIL_HOST', 'smtp.qq.com'),
    'port': int(os.getenv('MAIL_PORT', 465))
}

RECEIVERS = os.getenv('MAIL_RECEIVERS', 'admin@example.com').split(',')

This approach prevents sensitive tokens from appearing in version control while maintaining the same configuration structure expected by the send_email function.

Summary

• The HelloGitHub notification system uses a MAIL dictionary in script/github_bot/github_bot.py to configure SMTP authentication and server connection parameters.
• Available configuration keys include mail, username, password, host, and port, supporting standard SMTP with SSL/TLS encryption.
• Recipients are managed separately through the RECEIVERS list, allowing multiple email addresses to receive identical notification content.
• The send_email function implements the actual delivery logic using smtplib.SMTP_SSL, iterating through recipients after establishing an encrypted connection to the configured server.

Frequently Asked Questions

What SMTP server does HelloGitHub recommend?

The reference implementation in script/github_bot/github_bot.py uses QQ Mail (smtp.qq.com) with port 465 for SSL connections. However, the configuration is generic SMTP, so you can substitute any compatible provider such as Gmail, Outlook, or your organization's internal mail gateway by updating the host and port values in the MAIL dictionary.

How do I secure my email credentials?

Avoid hardcoding passwords in github_bot.py by loading sensitive values from environment variables. Use os.getenv() to retrieve the password, username, and other credentials at runtime. This prevents tokens from being exposed in version control and allows you to use container secrets or CI/CD environment variables for production deployments.

Can I send to multiple recipients?

Yes. The RECEIVERS variable is a Python list that supports one or more email addresses. The send_email function iterates through each entry in RECEIVERS and delivers the HTML notification content to every address listed. Simply append additional strings to the list to distribute alerts across a team or monitoring distribution list.

Where is the email sending logic implemented?

The email transmission logic resides in the send_email function defined at lines 86-108 of script/github_bot/github_bot.py. This function constructs a multipart HTML message, connects to the SMTP server using smtplib.SMTP_SSL with the credentials from the MAIL dictionary, and dispatches messages to each address in the RECEIVERS list.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}