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