# 邮件工具文档
## 概述
邮件工具提供了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
邮件内容
这是由外部构建的完整邮件内容
`)
// 发送邮件（工具只负责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邮件
`
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正文
",
}
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`