first commit

README.md

@@ -0,0 +1,195 @@
+# 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
+------------------------------------------------------------
+邮件正文:
+这是一封测试邮件的内容...
+============================================================
+```