195 lines
5.1 KiB
Markdown
195 lines
5.1 KiB
Markdown
# Stalwart 邮件 REST API Go客户端
|
||
|
||
这是一个用于管理 Stalwart 邮件服务器的 Go 客户端库，提供了简单易用的接口来创建和管理邮箱用户，以及查询邮件。
|
||
|
||
## 功能特点
|
||
|
||
- 创建邮箱用户（支持基本认证和API Key认证，自动生成随机安全密码）
|
||
- 查询用户列表
|
||
- 获取单个用户信息
|
||
- 获取邮箱最新邮件
|
||
|
||
## 安装要求
|
||
|
||
- Go 1.18+
|
||
- 依赖项：
|
||
- github.com/emersion/go-imap
|
||
- github.com/emersion/go-message
|
||
- gopkg.in/yaml.v3
|
||
|
||
## 构建和安装
|
||
|
||
克隆仓库后，使用以下命令构建：
|
||
|
||
```bash
|
||
cd go_stalwart_client
|
||
go mod tidy
|
||
go build -o bin/create_user cmd/create_user/main.go
|
||
go build -o bin/list_users cmd/list_users/main.go
|
||
go build -o bin/get_user cmd/get_user/main.go
|
||
go build -o bin/get_latest_email cmd/get_latest_email/main.go
|
||
```
|
||
|
||
## 配置文件
|
||
|
||
项目使用 `config/config.yaml` 进行配置，示例如下：
|
||
|
||
```yaml
|
||
api:
|
||
base_url: https://mail.evnmail.com/api
|
||
disable_proxy: true
|
||
user:
|
||
default_domain: evnmail.com
|
||
default_quota: 1073741824
|
||
auth:
|
||
basic:
|
||
username: admin
|
||
password: your_password_here
|
||
api_key: api_your_api_key_here
|
||
```
|
||
|
||
## 使用方法
|
||
|
||
### 创建用户
|
||
|
||
```bash
|
||
./bin/create_user -e user@evnmail.com -a apikey
|
||
```
|
||
|
||
如果不指定密码，系统会自动生成一个安全的随机密码。
|
||
|
||
参数说明：
|
||
- `-e, --email`: 邮箱地址
|
||
- `-p, --password`: 用户密码（可选，不提供则自动生成随机密码）
|
||
- `-d, --description`: 用户描述
|
||
- `-q, --quota`: 邮箱配额（字节）
|
||
- `-a, --auth`: 认证方式 (basic 或 apikey)
|
||
- `-u, --username`: 基本认证用户名
|
||
- `-P, --password`: 基本认证密码
|
||
- `-k, --apikey`: API Key
|
||
- `-c, --config`: 配置文件路径
|
||
|
||
### 查询用户列表
|
||
|
||
```bash
|
||
./bin/list_users -a basic -l 50 -p 1
|
||
```
|
||
|
||
参数说明：
|
||
- `-l, --limit`: 最大返回结果数量
|
||
- `-p, --page`: 页码
|
||
- `-q, --query`: 搜索关键词
|
||
- `-a, --auth`: 认证方式 (basic 或 apikey)
|
||
- `-u, --username`: 基本认证用户名
|
||
- `-P, --password`: 基本认证密码
|
||
- `-k, --apikey`: API Key
|
||
- `-c, --config`: 配置文件路径
|
||
|
||
### 获取单个用户信息
|
||
|
||
通过ID查询：
|
||
|
||
```bash
|
||
./bin/get_user -i 123 -a basic
|
||
```
|
||
|
||
通过邮箱查询：
|
||
|
||
```bash
|
||
./bin/get_user -e user@evnmail.com -a basic
|
||
```
|
||
|
||
参数说明：
|
||
- `-i, --id`: 用户ID
|
||
- `-e, --email`: 用户邮箱地址
|
||
- `-a, --auth`: 认证方式 (basic 或 apikey)
|
||
- `-u, --username`: 基本认证用户名
|
||
- `-P, --password`: 基本认证密码
|
||
- `-k, --apikey`: API Key
|
||
- `-c, --config`: 配置文件路径
|
||
|
||
### 获取邮箱最新邮件
|
||
|
||
```bash
|
||
./bin/get_latest_email -e user@evnmail.com -p password -n 3
|
||
```
|
||
|
||
注意：获取邮件时必须提供密码。
|
||
|
||
参数说明：
|
||
- `-e, --email`: 邮箱地址（默认: hayfzgul@evnmail.com）
|
||
- `-p, --password`: 邮箱密码（必填）
|
||
- `-s, --server`: IMAP服务器地址（默认: mail.evnmail.com）
|
||
- `-P, --port`: IMAP服务器端口（默认: 993）
|
||
- `-n, --number`: 获取的邮件数量（默认: 1）
|
||
- `--no-ssl`: 禁用SSL连接
|
||
- `-c, --config`: 配置文件路径
|
||
|
||
## 项目结构
|
||
|
||
```
|
||
go_stalwart_client/
|
||
├── cmd/ # 命令行应用
|
||
│ ├── create_user/ # 创建用户命令
|
||
│ ├── list_users/ # 列出用户命令
|
||
│ ├── get_user/ # 获取用户信息命令
|
||
│ └── get_latest_email/ # 获取最新邮件命令
|
||
├── pkg/ # 核心库
|
||
│ └── api/ # API实现
|
||
│ ├── config.go # 配置处理
|
||
│ ├── email_api.go # 用户API实现
|
||
│ └── email_fetch.go # 邮件获取实现
|
||
├── config/ # 配置目录
|
||
│ └── config.yaml # 配置文件
|
||
├── go.mod # Go模块定义
|
||
└── README.md # 说明文档
|
||
```
|
||
|
||
## 注意事项
|
||
|
||
1. 认证说明：
|
||
- 创建用户时推荐使用API Key认证
|
||
- 查询用户列表时推荐使用基本认证
|
||
- 根据服务器配置，某些功能可能受到权限限制
|
||
|
||
2. 错误处理：
|
||
- 程序会详细输出错误信息，便于排查问题
|
||
- 对于获取单个用户详情可能出现"notFound"错误，这是服务器API限制
|
||
|
||
3. 安全提示：
|
||
- 创建用户时，如果不指定密码，系统会自动生成12位随机密码
|
||
- 生成的密码包含大小写字母、数字和特殊字符，提供较高的安全性
|
||
- 密码仅在创建成功后显示一次，请妥善保存
|
||
|
||
## 示例输出
|
||
|
||
创建用户成功后的输出：
|
||
|
||
```
|
||
=== 新创建的用户信息 ===
|
||
用户ID: 123
|
||
登录名: username
|
||
邮箱地址: username@evnmail.com
|
||
密码: A8f2@xLp9q!Z
|
||
|
||
登录信息:
|
||
- 登录名: username
|
||
- 密码: A8f2@xLp9q!Z
|
||
- 邮箱服务器: mail.evnmail.com
|
||
```
|
||
|
||
获取邮件成功后的输出：
|
||
|
||
```
|
||
============================================================
|
||
邮件 1/1
|
||
------------------------------------------------------------
|
||
主题: 测试邮件
|
||
发件人: sender@example.com
|
||
收件人: recipient@evnmail.com
|
||
日期: Wed, 1 Jan 2025 12:00:00 +0800
|
||
------------------------------------------------------------
|
||
邮件正文:
|
||
这是一封测试邮件的内容...
|
||
============================================================
|
||
``` |