# 邮件批量发送脚本

- [参数配置](#参数配置)
- [安装流程](#安装流程)
- [使用说明](#使用说明)
- [可选功能](#可选功能)

## 参数配置

配置批处理文件 (.bat) 时可以选择传入的参数。

留空使用默认设定值。

```
usage: main.py [-h] [--column-address COLUMN_ADDRESS] [--column-name COLUMN_NAME] [--column-code COLUMN_CODE] [--column-pays COLUMN_PAYS]
               [--column-sent COLUMN_SENT] [-a ADDRESS] [-p PASSWORD] [-t TIMEOUT] [-i INTERVAL] [-r ATTEMPTS]
               [url]

Bulk Email Sending（邮件批量发送脚本）

positional arguments:
  url                             邮箱网页端链接

options:
  -h, --help                      打印帮助信息并退出
  --column-address COLUMN_ADDRESS 字段“邮箱”列名称
  --column-name COLUMN_NAME       字段“主要联系人”列名称
  --column-code COLUMN_CODE       字段“客户编号”列名称
  --column-pays COLUMN_PAYS       字段“国家地区”列名称
  --column-sent COLUMN_SENT       字段“已发送”列名称
  -a, --address ADDRESS           邮箱地址
  -p, --password PASSWORD         邮箱密码
  -t, --timeout TIMEOUT           超时时长（秒）；默认值：60
  -i, --interval INTERVAL         间隔时长（秒）；默认值：10
  -r, --attempts ATTEMPTS         允许尝试次数；默认值：3
```

## 安装流程

> [!INFO]
> 在执行初始化脚本之前请确保 Python 已经正确安装并添加到 PATH 系统变量中。\
> (在安装向导中勾选 `Add Python to PATH` 选项)

### 系统要求

- Windows 10+
- Python 3.10+
- Git for windows
- Windows Terminal (可选)

### 安装步骤

> [!TIP]
> 在已经安装了 Windows Terminal 的 Windows 11 环境下，右键桌面（或文件资源管理器窗口），在弹出的菜单中可以找到 `在终端中打开` 的选项，点击可以打开终端。

1. 打开终端，克隆仓库到本地：

```console
git clone https://git.autistic.men/Ultimatron-France/bulk-email-sending-script.git 邮件批量发送
```

2. 进入 `邮件批量发送脚本` 文件夹下的 `profiles` 文件夹，双击运行 `setup-virtualenv` 批处理文件进行环境初始化。

3. 等待初始化完成，终端显示 `Press any key to continue...` 时关闭终端。

4. 编辑 `profiles` 文件夹下的 `profile-example` 批处理文件，分别将 `--address` 和 `--password` 参数对应的值更改为实际使用的邮箱账号密码，保存并退出文本编辑器。这个文件将作为脚本的**启动配置文件**。

5. （可选）将 `profile-example` 重命名为实际使用的邮箱账号名称，方便记忆。

## 使用说明

> [!NOTE]
> 由于脚本在初始化阶段需要连接到 Google 服务，在运行前请确保 VPN 已打开。

### 基本操作步骤

1. 准备需要发送的**邮件**和**客户列表**。客户列表必须包含 `邮箱` 字段（表头名称可自定义），并且为 XLSX 格式。

2. 双击运行 `profiles` 文件夹下的[启动配置文件](#操作步骤)，等待脚本初始化（初次运行会自动下载必要文件，需要一段时间）。

3. 脚本初始化完成，此时会打开带有两个标签页（第一个是配置页面，第二个是 IONOS 邮箱页面）的新浏览器实例，自动化程序尝试登录到 IONOS 邮件系统。

4. 登录完成，程序自动跳转到配置页面。在配置页面上单击 `Open` 按钮，在弹出的对话框中选择需要发送的客户列表，单击 `打开` 按钮。

5. 客户列表读取完成，程序自动跳转到 IONOS 邮箱页面。单击**草稿箱**按钮，在左侧列表中勾选需要发送的邮件（不支持多选）。

6. 打开配置页面，按需调整参数配置，单击 `Send` 按钮，随后立即打开 IONOS 邮箱页面，自动化程序开始运行。

> [!WARNING]
> 自动化程序运行时请避免最小化程序窗口、直接关闭窗口或在 IONOS 邮箱页面进行任何操作。

> [!NOTE]
> 无论是执行 `Send` 或是 `Resume` 操作，必须及时打开 IONOS 邮箱页面，否则自动化程序可能无法正常工作。

7. 自动化程序运行时，用户可以打开**配置页面**，单击页面上的操作按钮执行[相应操作](#用户界面说明)。

8. 自动化程序运行结束，程序自动跳转到配置页面，在页面上方有弹窗显示已发送数量、警告数和错误数。此时可关闭程序窗口，或进行下一轮发送操作。

### 用户界面说明

<details>
<summary>基本信息 (Basic Information)</summary>

| 显示名称 | 说明 | 备注 |
| --- | --- | --- |
| **File Name** | 文件名称 | |
| **From** | 发件人 | |
| **Progress** | 当前程序进度（已发送数量） | |
| **Uptime** | 程序运行时长 | |
| **Status** | 程序当前状态 | `Idle`, `Ready`, `Running`, `Standby` |
| **Subject** | 邮件主题 | |
| **Recipient** | 收件人 | |
| **Timezone** | 当前时区 | 由 `Locale` 参数控制 |
| **Remaining** | 待发送数量 | |
| **Open** | 打开文件 | 仅在 `Idle` 状态下可见 |
| **Send** | 开始发送 | 仅在 `Ready` 状态下可见 |
| **Pause** | 暂停 | 仅在 `Running` 状态下可见 |
| **Resume** | 恢复 | 仅在 `Standby` 状态下可见 |
| **Skip** | 跳过 | |
| **Cancel** | 取消 | |
</details>

<details>
<summary>基本参数 (Parameters)</summary>

| 显示名称 | 说明 | 备注 |
| --- | --- | --- |
| **Timeout** | 超时时长 | 单位：秒 |
| **Interval** | 间隔时长 | 单位：秒 |
| **Max Occurrence** | 最大允许重复次数 | 由 `Avoid Spamming` 选项控制 |
| **Attempts** | 操作最大尝试次数 | |
| **Locale** | 语言和时区 | 仅当 `Greet recipients` 选项启用时有效果 |
| **Greet recipients** | 使用问候语 | |
| **Enable Task Slicing** | 启用任务切片功能 | |
| **Avoid Spamming** | 避免重复发送 | |
| **Save to File** | 保存发送记录 | 默认启用 |
</details>

<details>
<summary>列表字段配置 (Columns)</summary>

| 显示名称 | 说明 | 备注 |
| --- | --- | --- |
| **Recipient Address** | 收件人邮箱地址 | 必填 |
| **Recipient Name** | 收件人名称 | |
| **Reference Code** | 客户编号 | |
| **Country** | 国家地区 | |
| **Remarks** | 发送标记 | |
| **Variables** | 自定义变量 | |
</details>

<details>
<summary>任务切片 (Slicing)</summary>

| 显示名称 | 说明 | 备注 |
| --- | --- | --- |
| **Group By** | 分组依据 | |
| **Chunk Size** | 块大小 | 最小值：500 |
| **Offset** | 偏移量 | 最小值：0 |
| **Max** | 最大值 | |
| **Subcategory** | 子类目 | 由 `Group By` 选项控制 |
</details>

## 可选功能

### 使用问候语 (Greet Recipients)

### 任务切片 (Task Slicing)

### 避免重复发送 (Avoid Spamming)

### 保存发送记录 (Save to File)

### 列表字段调整