mail_api_go/README.md

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

构建和安装

克隆仓库后，使用以下命令构建：

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 进行配置，示例如下：

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

使用方法

创建用户

./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: 配置文件路径

查询用户列表

./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查询：

./bin/get_user -i 123 -a basic

通过邮箱查询：

./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: 配置文件路径

获取邮箱最新邮件

./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
------------------------------------------------------------
邮件正文:
这是一封测试邮件的内容...
============================================================