竹简文档
Email 邮件服务（可选）

Email 邮件服务

Bamboo Base 的可选邮件发送能力

Email 邮件服务（可选）

bamboo-base-go 的核心是 HTTP + 节点化初始化；Email 属于可选扩展能力，按需接入。

适用场景：

  • 用户注册后发送欢迎邮件
  • 身份验证时发送验证码邮件
  • 密码重置时发送重置链接
  • 业务通知邮件（订单确认、系统告警等）

快速入口

Message 消息定义

Template 模板系统

快速开始

功能特性

  • SMTP 协议: 基于 go-mail 库，支持标准 SMTP 协议
  • 多种 TLS 策略: 支持 none、starttls（默认）、tls 三种 TLS 策略
  • HTML / 纯文本: 支持同时发送 HTML 和纯文本内容，客户端自动选择
  • 模板引擎: 内置 Go html/template 模板引擎，支持验证码、欢迎、重置密码等内置模板
  • 自定义模板: 支持加载外部模板目录，同名模板覆盖内置模板
  • 附件支持: 支持文件和 io.Reader 两种附件添加方式
  • 节点化注入: 通过 xRegNode 注册到上下文，在 Handler 中通过 xCtxUtil 获取

模块导入

import xEmail "github.com/bamboo-services/bamboo-base-go/plugins/email"

环境变量配置

在 .env 文件中添加邮件服务配置：

.env
# 邮件服务配置

# SMTP 服务器地址 [必填]
EMAIL_HOST=smtp.example.com

# SMTP 端口 (25/465/587) [必填，默认 587]
EMAIL_PORT=587

# SMTP 认证用户名 [必填]
EMAIL_USER=your_email@example.com

# SMTP 认证密码 [必填]
EMAIL_PASS=your_password

# 发件人地址 [必填]
EMAIL_FROM=noreply@example.com

# 发件人名称 [可选]
EMAIL_FROM_NAME=Bamboo Service

# TLS 策略 (none/starttls/tls) [可选，默认 starttls]
EMAIL_TLS=starttls

# 外部邮件模板目录 [可选]
EMAIL_TEMPLATE_DIR=

TLS 策略说明

策略说明典型端口
starttls先以明文连接，再升级为 TLS（默认）587
tls直接使用 SSL/TLS 加密连接465
none不使用 TLS（不推荐用于生产环境）25

注册邮件客户端

通过节点化系统注册邮件客户端，与数据库、Redis 等组件统一管理：

main.go
package main

import (
    "context"

    xCtx "github.com/bamboo-services/bamboo-base-go/defined/context"
    xLog "github.com/bamboo-services/bamboo-base-go/common/log"
    xMain "github.com/bamboo-services/bamboo-base-go/major/main"
    xReg "github.com/bamboo-services/bamboo-base-go/major/register"
    xRegNode "github.com/bamboo-services/bamboo-base-go/major/register/node"
    xEmail "github.com/bamboo-services/bamboo-base-go/plugins/email"
    "your-project/internal/app/startup"
    "your-project/internal/app/route"
)

func main() {
    reg := xReg.Register(context.Background(), []xRegNode.RegNodeList{
        {Key: xCtx.DatabaseKey, Node: startup.InitDatabase},
        {Key: xCtx.RedisClientKey, Node: startup.InitRedis},
        {Key: xCtx.EmailClientKey, Node: xEmail.InitClient},  // 注册邮件客户端
    })

    log := xLog.WithName(xLog.NamedMAIN)
    xMain.Runner(reg, log, route.NewRoute)
}

InitClient 会自动从环境变量读取 SMTP 配置并创建邮件客户端实例。

在 Handler 中使用

注册完成后，可在 Handler 中通过 xCtxUtil 获取邮件客户端：

handler/user.go
package handler

import (
    xCtxUtil "github.com/bamboo-services/bamboo-base-go/common/utility/context"
    xEmail "github.com/bamboo-services/bamboo-base-go/plugins/email"
    "github.com/gin-gonic/gin"
)

func SendVerification(c *gin.Context) {
    ctx := c.Request.Context()

    // 获取邮件客户端
    emailClient := xCtxUtil.MustGetEmailClient(ctx)

    // 发送验证码邮件
    err := emailClient.SendTemplate(ctx, &xEmail.Message{
        To:      []string{"user@example.com"},
        Subject: "验证码",
        Template: "verification",
        TemplateData: map[string]string{
            "Code":   "123456",
            "Expire": "5 分钟",
        },
    })
    if err != nil {
        // 处理发送失败
        return
    }
}

核心 API

Send — 发送邮件

根据 Message 构建并发送邮件。支持纯文本、HTML 以及附件。

func (c *EmailClient) Send(ctx context.Context, msg *Message) error

SendHTML — 发送 HTML 邮件

SendHTML 是 Send 的别名，当 Message.HTMLBody 不为空时自动以 HTML 为主内容。

func (c *EmailClient) SendHTML(ctx context.Context, msg *Message) error

SendTemplate — 使用模板发送邮件

渲染指定模板并将结果作为 HTML 内容发送。

func (c *EmailClient) SendTemplate(ctx context.Context, msg *Message) error

参数要求：

  • msg.Template 不能为空，指定模板名称（如 "verification"、"welcome"）
  • msg.TemplateData 为模板数据，传入模板所需的变量

AddTemplateDir — 添加外部模板目录

动态添加外部模板目录，同名模板覆盖内置模板。

func (c *EmailClient) AddTemplateDir(dir string) error

ListTemplates — 列出可用模板

返回当前所有可用的模板名称列表。

func (c *EmailClient) ListTemplates() []string

快速示例

发送纯文本邮件

emailClient := xCtxUtil.MustGetEmailClient(ctx)

err := emailClient.Send(ctx, &xEmail.Message{
    To:       []string{"user@example.com"},
    Subject:  "系统通知",
    TextBody: "您的订单已确认。",
})

发送 HTML 邮件

emailClient := xCtxUtil.MustGetEmailClient(ctx)

err := emailClient.Send(ctx, &xEmail.Message{
    To:       []string{"user@example.com"},
    Subject:  "欢迎",
    HTMLBody: "<h1>欢迎注册！</h1><p>感谢您的加入。</p>",
    TextBody: "欢迎注册！感谢您的加入。",  // 纯文本备选
})

使用模板发送验证码

emailClient := xCtxUtil.MustGetEmailClient(ctx)

err := emailClient.SendTemplate(ctx, &xEmail.Message{
    To:       []string{"user@example.com"},
    Subject:  "邮箱验证码",
    Template: "verification",
    TemplateData: map[string]string{
        "Code":   "836521",
        "Expire": "5 分钟",
    },
})

发送带附件的邮件

emailClient := xCtxUtil.MustGetEmailClient(ctx)

msg := xEmail.NewMessage()
msg.To = []string{"user@example.com"}
msg.Subject = "月度报告"
msg.HTMLBody = "<p>请查收附件中的月度报告。</p>"

// 添加附件
msg.AttachReader("report.pdf", bytes.NewReader(pdfData))

err := emailClient.Send(ctx, msg)

发送抄送和密送

emailClient := xCtxUtil.MustGetEmailClient(ctx)

err := emailClient.Send(ctx, &xEmail.Message{
    To:      []string{"user@example.com"},
    Cc:      []string{"manager@example.com"},      // 抄送
    Bcc:     []string{"archive@example.com"},      // 密送
    ReplyTo: "support@example.com",                // 回复地址
    Subject: "项目更新",
    HTMLBody: "<p>项目已更新。</p>",
})

内置模板

Email 插件内置了三套邮件模板，开箱即用：

模板名称说明模板数据
verification验证码邮件Code（验证码）、Expire（过期时间）
welcome欢迎注册邮件Username（用户名）
reset_password重置密码邮件ResetURL（重置链接）、Expire（过期时间）

详细模板用法参见 Template 模板系统。

日志集成

邮件服务使用 xLog 统一日志系统，日志标识为 EMAIL：

// 发送成功时记录
[INFO] [EMAIL] 邮件发送成功 to=[user@example.com] subject=验证码

// 发送失败时记录
[ERROR] [EMAIL] 发送邮件失败 error=...

注意事项

  • 必填配置: EMAIL_HOST、EMAIL_USER、EMAIL_PASS、EMAIL_FROM 为必填项，缺少任一项会导致 InitClient 返回错误。
  • 默认端口: 如果未配置 EMAIL_PORT，默认使用 587（STARTTLS 标准端口）。
  • 默认 TLS 策略: 如果未配置 EMAIL_TLS，默认使用 starttls。
  • 错误处理: MustGetEmailClient 在未找到客户端时会 panic，确保在开发阶段尽早发现问题。生产环境建议使用 GetEmailClient 进行优雅错误处理。
  • 模板覆盖: 外部模板目录中的同名模板会覆盖内置模板，便于自定义邮件样式。

下一步

Message 消息定义

Template 模板系统

上下文工具函数

Async 异步任务

Bamboo Base 的可选异步任务执行能力

Message 消息定义

邮件消息结构和附件管理

On this page

Email 邮件服务（可选）
快速入口
功能特性
模块导入
环境变量配置
TLS 策略说明
注册邮件客户端
在 Handler 中使用
核心 API
Send — 发送邮件
SendHTML — 发送 HTML 邮件
SendTemplate — 使用模板发送邮件
AddTemplateDir — 添加外部模板目录
ListTemplates — 列出可用模板
快速示例
发送纯文本邮件
发送 HTML 邮件
使用模板发送验证码
发送带附件的邮件
发送抄送和密送
内置模板
日志集成
注意事项
下一步