shiran
fe43b9bdce
- 将README从英文翻译为中文 - 添加详细的API参考文档，包括所有管理接口和枚举值说明 - 补充安装、快速开始、认证方式等使用指南 refactor(client): 优化客户端代码结构并添加详细注释 - 为所有API方法添加中文注释和使用说明 - 改进Client结构体和Option配置的设计 - 统一错误处理和响应结构的文档说明
128 lines
3.8 KiB
Go
128 lines
3.8 KiB
Go
// Package emailcli 提供 Email Server 后端 API 的 Go 客户端。
|
|
//
|
|
// 两种客户端：
|
|
// - NewServiceClient: 使用 SERVICE_TOKEN，访问所有 /api/v1 管理接口
|
|
// （账号/签名/配额/通道/审核/队列/健康检查等）。
|
|
// - NewAppClient: 使用 App Key + App Secret，仅用于 POST /api/v1/mail/send 发送邮件。
|
|
//
|
|
// 快速上手：
|
|
//
|
|
// client := emailcli.NewServiceClient("https://server.com", "service-token")
|
|
// accounts, err := client.ListAccounts(ctx, emailcli.AccountListQuery{
|
|
// PaginationQuery: emailcli.PaginationQuery{Page: 1, PageSize: 20},
|
|
// })
|
|
//
|
|
// mailer := emailcli.NewAppClient("https://server.com", "app-key", "app-secret")
|
|
// resp, err := mailer.SendMail(ctx, emailcli.SendMailReq{
|
|
// To: []string{"recipient@example.com"},
|
|
// Subject: "Hello", Body: "<h1>Hi</h1>",
|
|
// })
|
|
//
|
|
// 所有后端接口统一返回：
|
|
//
|
|
// { "code": 200, "message": "ok", "data": <业务数据> }
|
|
//
|
|
// SDK 会自动解包 data；当 code != 200 时返回 *APIError。
|
|
//
|
|
// 枚举值集中在此常量表，调用方可直接使用，避免手写 magic number。
|
|
package emailcli
|
|
|
|
// --- Account.Status / Channel.Status / SenderAccount.Status / MailQuota.Status 通用启禁用 ---
|
|
const (
|
|
StatusDisabled int8 = 0 // 禁用
|
|
StatusEnabled int8 = 1 // 启用
|
|
)
|
|
|
|
// --- Account.AuditMode 账号审核模式 ---
|
|
const (
|
|
AuditModeNone int8 = 0 // 免审核，直接入队
|
|
AuditModeAuto int8 = 1 // 自动审核，由规则判定
|
|
AuditModeManual int8 = 2 // 人工审核
|
|
)
|
|
|
|
// --- Signature.Status 签名状态 ---
|
|
const (
|
|
SignatureStatusPending int8 = 0 // 待审核
|
|
SignatureStatusApproved int8 = 1 // 已通过
|
|
SignatureStatusRejected int8 = 2 // 已驳回
|
|
)
|
|
|
|
// --- MailLog.Status 邮件状态 ---
|
|
const (
|
|
MailStatusPendingAudit int8 = 0 // 待审核
|
|
MailStatusQueued int8 = 1 // 排队中
|
|
MailStatusSending int8 = 2 // 发送中
|
|
MailStatusSuccess int8 = 3 // 成功
|
|
MailStatusFailed int8 = 4 // 失败
|
|
MailStatusAbandoned int8 = 5 // 放弃
|
|
MailStatusRejected int8 = 6 // 驳回
|
|
)
|
|
|
|
// --- MailQuota.QuotaType 配额类型 ---
|
|
const (
|
|
QuotaTypeTotal int8 = 1 // 总量配额
|
|
QuotaTypeCycle int8 = 2 // 周期配额，需要配合 CycleUnit
|
|
)
|
|
|
|
// --- MailQuota.CycleUnit 周期单位，仅在 QuotaType=2 时生效 ---
|
|
const (
|
|
CycleUnitDay = "day"
|
|
CycleUnitWeek = "week"
|
|
CycleUnitMonth = "month"
|
|
CycleUnitYear = "year"
|
|
)
|
|
|
|
// --- Channel.Strategy 通道下多发信账号的挑选策略 ---
|
|
const (
|
|
StrategyRoundRobin = "round_robin" // 轮询（默认）
|
|
StrategyWeight = "weight" // 按 Weight 加权随机
|
|
StrategyLeastUsed = "least_used" // 今日发送数最少优先
|
|
)
|
|
|
|
// --- AuditRule.Action 规则命中后的动作 ---
|
|
const (
|
|
RuleActionApprove int8 = 1 // 自动通过
|
|
RuleActionReject int8 = 2 // 自动驳回
|
|
RuleActionToManual int8 = 3 // 转人工审核
|
|
)
|
|
|
|
// --- AuditRule.RuleType 规则匹配方式 ---
|
|
const (
|
|
RuleTypeKeyword = "keyword" // 关键词包含
|
|
RuleTypeRegex = "regex" // 正则匹配
|
|
RuleTypeDomain = "domain" // 域名匹配
|
|
)
|
|
|
|
// --- AuditRule.Target 规则匹配目标 ---
|
|
const (
|
|
RuleTargetSubject = "subject"
|
|
RuleTargetBody = "body"
|
|
RuleTargetTo = "to"
|
|
RuleTargetFrom = "from"
|
|
)
|
|
|
|
// --- MailAudit.AuditType 审核来源 ---
|
|
const (
|
|
AuditTypeAuto int8 = 1 // 规则自动
|
|
AuditTypeManual int8 = 2 // 人工
|
|
)
|
|
|
|
// --- MailAudit.Action 审核动作 ---
|
|
const (
|
|
AuditActionApprove int8 = 1 // 通过
|
|
AuditActionReject int8 = 2 // 驳回
|
|
)
|
|
|
|
// --- SendMailReq.ContentType 邮件正文类型 ---
|
|
const (
|
|
ContentTypeText = "text/plain"
|
|
ContentTypeHTML = "text/html"
|
|
)
|
|
|
|
// --- SendMailResp.Status 发送结果状态 ---
|
|
const (
|
|
SendStatusQueued = "queued" // 已入队，待发送
|
|
SendStatusPendingAudit = "pending_audit" // 待人工审核
|
|
SendStatusRejected = "rejected" // 规则驳回
|
|
)
|