# gmail-api-client

**Repository Path**: hadeian/gmail-api-client

## Basic Information

- **Project Name**: gmail-api-client
- **Description**: gmail-api-client
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 1
- **Created**: 2024-08-13
- **Last Updated**: 2024-08-26

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Gmail API Client
Gmail API Client 是一个调用 Google Mail API 的客户端，能够根据指定的时间范围和关键字，获取指定邮箱内最新的一封包含关键字的邮件内容。

## 环境
- Python 版本：3.11 及以上
- Gmail API 服务账号密钥文件（JSON 格式）

## 安装依赖
在项目目录中，创建 requirements.txt 文件并添加以下内容：
```plaintext
Flask==3.0.3
google-api-python-client==2.140.0
google-auth==2.33.0
google-auth-httplib2==0.2.0
google-auth-oauthlib==1.2.1
beautifulsoup4==4.12.3
```
然后运行以下命令安装依赖：
```shell
pip install -r requirements.txt
```

## 部署
将 api-client.py 和服务账号密钥文件（例如 gmail-api-client.json）放在同一级目录下。

### 启动服务
前台运行：
```shell
python api-client.py
```
后台运行：
```shell
nohup python api-client.py &
```
或者使用 supervisor 管理程序运行，确保服务在崩溃或重启后自动重启。

#### 使用 supervisor 进行部署
1. 安装 supervisor
    ```shell
    sudo apt-get install supervisor
    ```
2. 创建 supervisor 配置文件 /etc/supervisor/conf.d/gmail-api-client.conf：
    ```editorconfig
    [program:gmail-api-client]
    command=/usr/bin/python3 /path/to/api-client.py
    directory=/path/to/your/project
    autostart=true
    autorestart=true
    stderr_logfile=/var/log/gmail-api-client.err.log
    stdout_logfile=/var/log/gmail-api-client.out.log
    ```
3. 启动 supervisor：
    ```shell
    sudo supervisorctl reread
    sudo supervisorctl update
    sudo supervisorctl start gmail-api-client
    ```

## 配置文件说明
在项目目录中创建 config.ini 文件，内容如下：
```editorconfig
[logging]
log_level = INFO  # 记录日志级别，可选：DEBUG、INFO、WARNING、ERROR、CRITICAL
log_file = gmail-api-client.log  # 日志文件名

[gmail]
service_account_file = gmail-api-client.json  # 服务账号密钥文件名
scopes = https://www.googleapis.com/auth/gmail.readonly  # Gmail API 的访问权限范围

[flask]
host = 0.0.0.0  # 服务监听地址，保持默认即可
port = 5000   # 服务启动端口
debug = false  # 部署生产环境时，关闭debug, 可选项：true、false
```

### 配置项说明
- log_level: 控制日志记录的详细程度。可以设置为 DEBUG、INFO、WARNING、ERROR 或 CRITICAL。
- log_file: 日志文件的名称。所有的日志将被记录在这个文件中。
- service_account_file: Gmail API 服务账号的密钥文件路径。
- scopes: Gmail API 的访问权限范围。一般为 https://www.googleapis.com/auth/gmail.readonly。
- host: Flask 服务的监听地址。0.0.0.0 表示监听所有网络接口。
- port: Flask 服务的启动端口。
- debug: 是否开启 Flask 的调试模式。在生产环境中应设置为 false。

## API调用
### 获取指定邮箱内最新一封包含关键字的邮件
- 请求方式: POST
- URL: /get_latest_email

**请求参数**

| 参数名称	       | 类型	        | 必填  | 说明                                    |
|-------------|------------| ---- |---------------------------------------|
| email	      | string     | 是	 | 需要查询的 Gmail 邮箱地址                      |
| keyword	    | string     | 否	 | 搜索关键字。如果不提供，则返回时间范围内的最新一封邮件           |
| after_time	 | string/int | 否	 | 指定时间范围，结合`time_type`参数使用，默认取最近时间的一封邮件 |
| time_type	  | string     | 否	 | 时间单位，M 表示分钟（默认），H 表示小时                |

**请求示例**
```json
{
    "email": "example@gmail.com",
    "keyword": "verification code",
    "after_time": "72",
    "time_type": "H"
}
```
在这个示例中，请求将获取 example@gmail.com 邮箱中，过去 72 小时内包含关键字 "verification code" 的最新一封邮件。

**响应参数**

| 参数名称	| 类型	  | 说明                                           |
| ---------- | ------ |----------------------------------------------|
| status	| string	| 请求状态，success 表示成功，failure 表示失败               |
| email_content | string | 邮件原始内容文本                                     |
| verification_code | string	| 获取到的邮件内容中的验证码。如果 status 为 success，则包含邮件中的验证码 |
| total_matched_emails	| int	| 根据查询条件匹配到的邮件总数                               |
| message	| string	| 错误信息。当 status 为 failure 时，包含错误说明             |

**响应示例（成功）**
```json
{
    "status": "success",
    "email_content": "your verification code is 123456.",
    "verification_code": "123456",
    "total_matched_emails": 1
}
```

**响应示例（失败）**
```json
{
    "status": "failure",
    "message": "No messages found",
    "total_matched_emails": 0
}
```

## 使用方法
1. **配置项目：**
   - 确保 api-client.py、config.ini 和 Gmail API 的服务账号密钥文件（例如 gmail-api-client.json）位于同一目录下。
   - 编辑 config.ini 文件，更新日志配置、Gmail 服务账号配置以及 Flask 服务配置。

2. **启动服务：**
    - 使用命令 python api-client.py 启动 Flask 服务。
    - 服务启动后，将监听 config.ini 文件中指定的端口（默认为 5000）。

3. **发送请求：**
    - 使用 POST 请求调用 /get_latest_email API，查询指定邮箱在指定时间范围内的最新一封包含关键字的邮件。

4. **检查日志：**
    - 日志文件名和路径由 config.ini 文件中的 log_file 配置项指定。日志记录了 API 调用过程中的关键步骤和错误信息，便于调试和维护。

## 常见问题
1. **如何更新服务账号密钥？**
   - 将新的服务账号密钥文件替换 config.ini 文件中 service_account_file 指定的文件即可。

2. **如何更改日志级别？**
   - 修改 config.ini 文件中 log_level 配置项为所需的日志级别（例如 DEBUG、INFO 等），然后重启服务。

3. **如何处理查询失败？**
   - 检查返回的 message 信息，通常是由于邮箱地址错误或未匹配到符合条件的邮件。可以通过查看日志获取详细的错误信息。