333 lines
7.0 KiB
Markdown
333 lines
7.0 KiB
Markdown
# 邮件工具文档
|
||
|
||
## 概述
|
||
|
||
邮件工具提供了SMTP邮件发送功能，使用Go标准库实现，无需第三方依赖。
|
||
|
||
## 功能特性
|
||
|
||
- 支持SMTP邮件发送
|
||
- 支持TLS/SSL加密
|
||
- 支持发送原始邮件内容（完全由外部控制）
|
||
- 支持便捷方法发送简单邮件
|
||
- 使用配置工具统一管理配置
|
||
|
||
## 使用方法
|
||
|
||
### 1. 创建邮件发送器
|
||
|
||
```go
|
||
import (
|
||
"git.toowon.com/jimmy/go-common/config"
|
||
"git.toowon.com/jimmy/go-common/email"
|
||
)
|
||
|
||
// 从配置加载
|
||
cfg, err := config.LoadFromFile("./config.json")
|
||
if err != nil {
|
||
log.Fatal(err)
|
||
}
|
||
|
||
emailConfig := cfg.GetEmail()
|
||
if emailConfig == nil {
|
||
log.Fatal("email config is nil")
|
||
}
|
||
|
||
// 创建邮件发送器
|
||
mailer, err := email.NewEmail(emailConfig)
|
||
if err != nil {
|
||
log.Fatal(err)
|
||
}
|
||
```
|
||
|
||
### 2. 发送原始邮件内容（推荐，最灵活）
|
||
|
||
```go
|
||
// 外部构建完整的邮件内容（MIME格式）
|
||
emailBody := []byte(`From: sender@example.com
|
||
To: recipient@example.com
|
||
Subject: 邮件主题
|
||
Content-Type: text/html; charset=UTF-8
|
||
|
||
<html>
|
||
<body>
|
||
<h1>邮件内容</h1>
|
||
<p>这是由外部构建的完整邮件内容</p>
|
||
</body>
|
||
</html>
|
||
`)
|
||
|
||
// 发送邮件（工具只负责SMTP发送，不构建内容）
|
||
err := mailer.SendRaw(
|
||
[]string{"recipient@example.com"}, // 收件人列表
|
||
emailBody, // 完整的邮件内容
|
||
)
|
||
if err != nil {
|
||
log.Fatal(err)
|
||
}
|
||
```
|
||
|
||
### 3. 发送简单邮件（便捷方法）
|
||
|
||
```go
|
||
// 发送纯文本邮件（内部会构建邮件内容）
|
||
err := mailer.SendSimple(
|
||
[]string{"recipient@example.com"},
|
||
"邮件主题",
|
||
"邮件正文内容",
|
||
)
|
||
if err != nil {
|
||
log.Fatal(err)
|
||
}
|
||
```
|
||
|
||
### 4. 发送HTML邮件（便捷方法）
|
||
|
||
```go
|
||
// 发送HTML邮件（内部会构建邮件内容）
|
||
htmlBody := `
|
||
<html>
|
||
<body>
|
||
<h1>欢迎</h1>
|
||
<p>这是一封HTML邮件</p>
|
||
</body>
|
||
</html>
|
||
`
|
||
|
||
err := mailer.SendHTML(
|
||
[]string{"recipient@example.com"},
|
||
"邮件主题",
|
||
htmlBody,
|
||
)
|
||
if err != nil {
|
||
log.Fatal(err)
|
||
}
|
||
```
|
||
|
||
### 5. 使用Message结构发送（便捷方法）
|
||
|
||
```go
|
||
import "git.toowon.com/jimmy/go-common/email"
|
||
|
||
msg := &email.Message{
|
||
To: []string{"to@example.com"},
|
||
Cc: []string{"cc@example.com"},
|
||
Bcc: []string{"bcc@example.com"},
|
||
Subject: "邮件主题",
|
||
Body: "纯文本正文",
|
||
HTMLBody: "<html><body><h1>HTML正文</h1></body></html>",
|
||
}
|
||
|
||
err := mailer.Send(msg)
|
||
if err != nil {
|
||
log.Fatal(err)
|
||
}
|
||
```
|
||
|
||
## API 参考
|
||
|
||
### NewEmail(cfg *config.EmailConfig) (*Email, error)
|
||
|
||
创建邮件发送器。
|
||
|
||
**参数：**
|
||
- `cfg`: 邮件配置对象
|
||
|
||
**返回：** 邮件发送器实例和错误信息
|
||
|
||
### (e *Email) SendRaw(recipients []string, body []byte) error
|
||
|
||
发送原始邮件内容（推荐使用，最灵活）。
|
||
|
||
**参数：**
|
||
- `recipients`: 收件人列表（To、Cc、Bcc的合并列表）
|
||
- `body`: 完整的邮件内容（MIME格式），由外部构建
|
||
|
||
**返回：** 错误信息
|
||
|
||
**说明：** 此方法允许外部完全控制邮件内容，工具只负责SMTP发送。
|
||
|
||
### (e *Email) Send(msg *Message) error
|
||
|
||
发送邮件（使用Message结构，内部会构建邮件内容）。
|
||
|
||
**参数：**
|
||
- `msg`: 邮件消息对象
|
||
|
||
**返回：** 错误信息
|
||
|
||
**说明：** 如果需要完全控制邮件内容，请使用SendRaw方法。
|
||
|
||
### (e *Email) SendSimple(to []string, subject, body string) error
|
||
|
||
发送简单邮件（便捷方法）。
|
||
|
||
**参数：**
|
||
- `to`: 收件人列表
|
||
- `subject`: 主题
|
||
- `body`: 正文
|
||
|
||
### (e *Email) SendHTML(to []string, subject, htmlBody string) error
|
||
|
||
发送HTML邮件（便捷方法）。
|
||
|
||
**参数：**
|
||
- `to`: 收件人列表
|
||
- `subject`: 主题
|
||
- `htmlBody`: HTML正文
|
||
|
||
### Message 结构体
|
||
|
||
```go
|
||
type Message struct {
|
||
To []string // 收件人列表
|
||
Cc []string // 抄送列表（可选）
|
||
Bcc []string // 密送列表（可选）
|
||
Subject string // 主题
|
||
Body string // 正文（纯文本）
|
||
HTMLBody string // HTML正文（可选）
|
||
Attachments []Attachment // 附件列表（可选）
|
||
}
|
||
```
|
||
|
||
### Attachment 结构体
|
||
|
||
```go
|
||
type Attachment struct {
|
||
Filename string // 文件名
|
||
Content []byte // 文件内容
|
||
ContentType string // 文件类型
|
||
}
|
||
```
|
||
|
||
## 配置说明
|
||
|
||
邮件配置通过 `config.EmailConfig` 提供：
|
||
|
||
| 字段 | 类型 | 说明 | 默认值 |
|
||
|------|------|------|--------|
|
||
| Host | string | SMTP服务器地址 | - |
|
||
| Port | int | SMTP服务器端口 | 587 |
|
||
| Username | string | 发件人邮箱 | - |
|
||
| Password | string | 邮箱密码或授权码 | - |
|
||
| From | string | 发件人邮箱地址 | Username |
|
||
| FromName | string | 发件人名称 | - |
|
||
| UseTLS | bool | 是否使用TLS | false |
|
||
| UseSSL | bool | 是否使用SSL | false |
|
||
| Timeout | int | 连接超时时间（秒） | 30 |
|
||
|
||
## 常见SMTP服务器配置
|
||
|
||
### Gmail
|
||
```json
|
||
{
|
||
"host": "smtp.gmail.com",
|
||
"port": 587,
|
||
"useTLS": true,
|
||
"useSSL": false
|
||
}
|
||
```
|
||
|
||
### QQ邮箱
|
||
```json
|
||
{
|
||
"host": "smtp.qq.com",
|
||
"port": 587,
|
||
"useTLS": true,
|
||
"useSSL": false
|
||
}
|
||
```
|
||
|
||
### 163邮箱
|
||
```json
|
||
{
|
||
"host": "smtp.163.com",
|
||
"port": 25,
|
||
"useTLS": false,
|
||
"useSSL": false
|
||
}
|
||
```
|
||
|
||
### 企业邮箱（SSL）
|
||
```json
|
||
{
|
||
"host": "smtp.exmail.qq.com",
|
||
"port": 465,
|
||
"useTLS": false,
|
||
"useSSL": true
|
||
}
|
||
```
|
||
|
||
## 注意事项
|
||
|
||
1. **推荐使用SendRaw方法**：
|
||
- `SendRaw`方法允许外部完全控制邮件内容
|
||
- 可以构建任意格式的MIME邮件（包括复杂附件、多部分内容等）
|
||
- 工具只负责SMTP发送，不构建内容
|
||
|
||
2. **邮件内容构建**：
|
||
- 使用`SendRaw`时，需要外部构建完整的MIME格式邮件内容
|
||
- 可以参考RFC 5322标准构建邮件内容
|
||
- 便捷方法（`Send`、`SendSimple`、`SendHTML`）内部会构建简单格式的邮件内容
|
||
|
||
3. **密码/授权码**：
|
||
- 很多邮箱服务商需要使用授权码而不是登录密码
|
||
- Gmail、QQ邮箱等需要开启SMTP服务并获取授权码
|
||
|
||
4. **端口选择**：
|
||
- 587端口：通常使用TLS（STARTTLS）
|
||
- 465端口：通常使用SSL
|
||
- 25端口：通常不使用加密（不推荐）
|
||
|
||
5. **TLS vs SSL**：
|
||
- UseTLS=true：使用STARTTLS（推荐，端口587）
|
||
- UseSSL=true：使用SSL（端口465）
|
||
|
||
6. **错误处理**：
|
||
- 所有操作都应该进行错误处理
|
||
- 建议记录详细的错误日志
|
||
|
||
## 完整示例
|
||
|
||
```go
|
||
package main
|
||
|
||
import (
|
||
"log"
|
||
|
||
"git.toowon.com/jimmy/go-common/config"
|
||
"git.toowon.com/jimmy/go-common/email"
|
||
)
|
||
|
||
func main() {
|
||
// 加载配置
|
||
cfg, err := config.LoadFromFile("./config.json")
|
||
if err != nil {
|
||
log.Fatal(err)
|
||
}
|
||
|
||
// 创建邮件发送器
|
||
mailer, err := email.NewEmail(cfg.GetEmail())
|
||
if err != nil {
|
||
log.Fatal(err)
|
||
}
|
||
|
||
// 发送邮件
|
||
err = mailer.SendSimple(
|
||
[]string{"recipient@example.com"},
|
||
"测试邮件",
|
||
"这是一封测试邮件",
|
||
)
|
||
if err != nil {
|
||
log.Fatal(err)
|
||
}
|
||
|
||
log.Println("邮件发送成功")
|
||
}
|
||
```
|
||
|
||
## 示例
|
||
|
||
完整示例请参考 `examples/email_example.go`
|
||
|