From 9444bf4802f0bf373ba724b44386152f40856ee6 Mon Sep 17 00:00:00 2001 From: huangzhenpc Date: Fri, 23 May 2025 23:06:09 +0800 Subject: [PATCH] first commit --- README.md | 195 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 195 insertions(+) create mode 100644 README.md diff --git a/README.md b/README.md new file mode 100644 index 0000000..f306f02 --- /dev/null +++ b/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 +------------------------------------------------------------ +邮件正文: +这是一封测试邮件的内容... +============================================================ +``` \ No newline at end of file