jimmy/go-common
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
f62e8ecebfd84901753accc7d0e36da707a746ac
go-common/docs/email.md
Jimmy Xue a655640ab2 修改包名
2025-11-30 13:43:43 +08:00

7.0 KiB
Raw Blame History

邮件工具文档

概述

邮件工具提供了SMTP邮件发送功能，使用Go标准库实现，无需第三方依赖。

功能特性

  • 支持SMTP邮件发送
  • 支持TLS/SSL加密
  • 支持发送原始邮件内容（完全由外部控制）
  • 支持便捷方法发送简单邮件
  • 使用配置工具统一管理配置

使用方法

1. 创建邮件发送器

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. 发送原始邮件内容（推荐，最灵活）

// 外部构建完整的邮件内容（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. 发送简单邮件（便捷方法）

// 发送纯文本邮件（内部会构建邮件内容）
err := mailer.SendSimple(
    []string{"recipient@example.com"},
    "邮件主题",
    "邮件正文内容",
)
if err != nil {
    log.Fatal(err)
}

4. 发送HTML邮件（便捷方法）

// 发送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结构发送（便捷方法）

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 结构体

type Message struct {
    To          []string      // 收件人列表
    Cc          []string      // 抄送列表（可选）
    Bcc         []string      // 密送列表（可选）
    Subject     string        // 主题
    Body        string        // 正文（纯文本）
    HTMLBody    string        // HTML正文（可选）
    Attachments []Attachment  // 附件列表（可选）
}

Attachment 结构体

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

{
  "host": "smtp.gmail.com",
  "port": 587,
  "useTLS": true,
  "useSSL": false
}

QQ邮箱

{
  "host": "smtp.qq.com",
  "port": 587,
  "useTLS": true,
  "useSSL": false
}

163邮箱

{
  "host": "smtp.163.com",
  "port": 25,
  "useTLS": false,
  "useSSL": false
}

企业邮箱（SSL）

{
  "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. 错误处理：

    • 所有操作都应该进行错误处理
    • 建议记录详细的错误日志

完整示例

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