# HelloGitHub Email Configuration Options for the Notification System

> Explore HelloGitHub email configuration options, including SMTP settings in the MAIL dictionary and RECEIVERS list, for its automated notification system.

- Repository: [削微寒/HelloGitHub](https://github.com/521xueweihan/HelloGitHub)
- Tags: getting-started
- Published: 2026-02-25

---

**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`](https://github.com/521xueweihan/HelloGitHub/blob/main/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`](https://github.com/521xueweihan/HelloGitHub/blob/main/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:

```python
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`](https://github.com/521xueweihan/HelloGitHub/blob/main/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`](https://github.com/521xueweihan/HelloGitHub/blob/main/script/github_bot/github_bot.py):

```python
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:

```python
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`](https://github.com/521xueweihan/HelloGitHub/blob/main/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`](https://github.com/521xueweihan/HelloGitHub/blob/main/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`](https://github.com/521xueweihan/HelloGitHub/blob/main/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`](https://github.com/521xueweihan/HelloGitHub/blob/main/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.