使用 Golang 对接亚马逊 Simple Email Service 发送邮件

2022-09-27 今日头条全栈社畜小吉

写在前边：国内有很多的邮件服务商，尤其几个大的云厂商都有非常成熟的邮件推送服务，如果可以的话，建议大家直接使用国内云厂商的服务。我们公司因为做的国际业务，很多东西都在亚马逊，所以拗不过我们老大，只能使用 AWS 的 SES；

进入正题，首先我们需要下载亚马逊的 SDK , 执行 go get ，我这里用的是 1.43.15 版本(不同版本之间亚马逊可能会进行细微调整)。

go get github.com/aws/aws-sdk-go@v1.43.15

当然，基本上所有云厂商都支持使用 SMTP 的方式发送邮件，各大语言均对 SMTP 有较好的支持，本文不介绍SMTP，介绍的是 SES 的模板发送。

模板发送的好处有很多，类似于强类型语言，虽然写起来复杂，但是我们在编写过程中的错误可以更好地暴露出来；其他优点不再赘述。

完整源码

先上代码，如果代码阅读能力比较强的同学，可以直接拿走开始用了,使用方法比较简单，将这个代码新建一个文件，初始化一下，在需要发邮件的地方，调用即可，后边会展开对下方代码的分析解读；

tip: 代码里边的 xlog 是我们自己封装的一个log包，换成fmt打印或者自己的日志包

package aws_ses

import (
	"context"
	"encoding/json"
	"github.com/aws/aws-sdk-go/aws"
	"github.com/aws/aws-sdk-go/aws/credentials"
	"github.com/aws/aws-sdk-go/aws/session"
	"github.com/aws/aws-sdk-go/service/sesv2"
	"github.com/aws/aws-sdk-go/service/sesv2/sesv2iface"
	"github.com/microcosm-cc/bluemonday"
)

const (
	AwsRegion                      = "us-west-2" // 此处填写你自己的亚马逊所属地区
	Endpoint                       = "https://email-smtp.us-west-2.amazonaws.com" // 此处是对应的所处地址 host
	FeedbackForwardingEmailAddress = "" // 发生错误时亚马逊通知地址，前提是开通了aws配套的SNS 花不了多少钱，强烈建议开启，否则你发不出来邮件，不知道怎么回事儿。。。
)

type AwsSesRepo struct {
	SesV2BioAPI sesv2iface.SESV2API
}

func NewAwsSesRepo() *AwsSesRepo {
	ctx := context.Background()
	sess, err := session.NewSession(&aws.Config{
		CredentialsChainVerboseErrors:     nil,
		Credentials:                       credentials.NewStaticCredentials(accessKey, accessSecret, ""),
		Endpoint:                          nil,
		EndpointResolver:                  nil,
		EnforceShouldRetryCheck:           nil,
		Region:                            aws.String(AwsRegion),
		DisableSSL:                        nil,
		HTTPClient:                        nil,
		LogLevel:                          nil,
		Logger:                            nil,
		MaxRetries:                        nil,
		Retryer:                           nil,
		DisableParamValidation:            nil,
		DisableComputeChecksums:           nil,
		S3ForcePathStyle:                  nil,
		S3Disable100Continue:              nil,
		S3UseAccelerate:                   nil,
		S3DisableContentMD5Validation:     nil,
		S3UseARNRegion:                    nil,
		LowerCaseHeaderMaps:               nil,
		EC2MetadataDisableTimeoutOverride: nil,
		UseDualStackEndpoint:              0,
		UseFIPSEndpoint:                   0,
		SleepDelay:                        nil,
		DisableRestProtocolURICleaning:    nil,
		EnableEndpointDiscovery:           nil,
		DisableEndpointHostPrefix:         nil,
		STSRegionalEndpoint:               0,
		S3UsEast1RegionalEndpoint:         0,
	})
	if err != nil {
		xlog.Error(ctx, "初始化亚马逊 session 出错", "err", err)
		return nil
	}
	svc := sesv2.New(sess)
	return &AwsSesRepo{
		Conf:        conf,
		SesV2BioAPI: svc,
	}
}

type SendEmailWithCtxParams struct {
	FromEmail    string
	TemplateName string
	ToAddress    []string
	BccAddress   []string
	CcAddress    []string
	TemplateData map[string]string
}

// 发送邮件.
func (r *AwsSesRepo) SendEmailWithContext(ctx context.Context, p *SendEmailWithCtxParams) (*sesv2.SendEmailOutput, error) {
	// 需要将结构体的内容json一下传递给发信接口
  templateDataStr, err := json.Marshal(p.TemplateData)
	if err != nil {
		return nil, err
	}
  // 如果没有设置from，建议在这个地方给个默认值
	if len(p.FromEmail) == 0 {
		p.FromEmail = "demo@toutiao.com" //默认值
	}
  // 调用 SDK 发送邮件
	resp, err := r.SesV2BioAPI.SendEmailWithContext(ctx, &sesv2.SendEmailInput{
		ConfigurationSetName: aws.String("default"), // 设置集 后边有详解
		Content: &sesv2.EmailContent{
			Raw:    nil, // 原始发送方式，需要自行拼装各种参数.
			Simple: nil,
			Template: &sesv2.Template{ // 使用模版方式发送
				TemplateArn:  nil,
				TemplateData: aws.String(string(templateDataStr)), // 模版需要的 value
				TemplateName: aws.String(p.TemplateName), // 模版的名称 必须 唯一
			},
		},
		Destination: &sesv2.Destination{
			BccAddresses: aws.StringSlice(p.BccAddress), // 密送
			CcAddresses:  aws.StringSlice(p.CcAddress),  // 抄送
			ToAddresses:  aws.StringSlice(p.ToAddress),  // 要发给谁
		},
		EmailTags:                                 nil, // 邮件的标签
		FeedbackForwardingEmailAddress:            nil,
		FeedbackForwardingEmailAddressIdentityArn: nil,
		FromEmailAddress:                          aws.String(p.FromEmail), // 谁发出的
		FromEmailAddressIdentityArn:               nil,
		ListManagementOptions:                     nil,                                              // 取消订阅时的通知时间tag.
		ReplyToAddresses:                          aws.StringSlice([]string{""}), // 用户收到邮件，进行回复时的邮件地址.
	})
	return resp, err
}

// 创建模版.
func (r *AwsSesRepo) CreateEmailTemplateWithContext(ctx context.Context, templateName, title, content string) (*sesv2.CreateEmailTemplateOutput, error) {
	p := bluemonday.UGCPolicy()
	outPut, err := r.SesV2BioAPI.CreateEmailTemplateWithContext(ctx, &sesv2.CreateEmailTemplateInput{
		TemplateContent: &sesv2.EmailTemplateContent{
			html:    aws.String(content),
			Subject: aws.String(title),
			Text:    aws.String(p.Sanitize(content)),
		},
		TemplateName: aws.String(templateName),
	})
	return outPut, err
}

// 获取单个邮件模版.
func (r *AwsSesRepo) GetEmailTemplateWithContext(ctx context.Context, templateName string) (*sesv2.GetEmailTemplateOutput, error) {
	info, err := r.SesV2BioAPI.GetEmailTemplateWithContext(ctx, &sesv2.GetEmailTemplateInput{
		TemplateName: aws.String(templateName),
	})
	if err != nil {
		xlog.Error(ctx, "GetEmailTemplateWithContext ", "err", err)
		return nil, err
	}
	return info, nil
}

// 修改模版
func (r *AwsSesRepo) UpdateEmailTemplateWithContext(ctx context.Context, templateName, html, text, title string) (*sesv2.UpdateEmailTemplateOutput, error) {
	data, err := r.SesV2BioAPI.UpdateEmailTemplateWithContext(ctx, &sesv2.UpdateEmailTemplateInput{
		TemplateContent: &sesv2.EmailTemplateContent{
			Html:    aws.String(html),
			Subject: aws.String(title),
			Text:    aws.String(text),
		},
		TemplateName: aws.String(templateName),
	})
	if err != nil {
		xlog.Error(ctx, "UpdateEmailTemplateWithContext ", "err", err)
		return nil, err
	}
	return data, nil
}

// 批量获取模版列表
func (r *AwsSesRepo) ListEmailTemplatesWithContext(ctx context.Context, pageSize int64, cursor string) (*sesv2.ListEmailTemplatesOutput, error) {
	data, err := r.SesV2BioAPI.ListEmailTemplatesWithContext(ctx, &sesv2.ListEmailTemplatesInput{
		NextToken: aws.String(cursor),
		PageSize:  aws.Int64(pageSize),
	})
	if err != nil {
		xlog.Error(ctx, "ListEmailTemplatesWithContext ", "err", err)
		return nil, err
	}
	return data, nil
}

如何使用：

func main(){
    sesRepo := NewAwsSesRepo()
    sesRepo.SendEmailWithContext(.....)
}

可以看到我只是对接了几个简单的接口

发送邮件
SendEmailWithContext
创建模版
CreateEmailTemplateWithContext
获取单个模版信息
GetEmailTemplateWithContext
更新模版
UpdateEmailTemplateWithContext
批量获取模版列表
ListEmailTemplatesWithContext

其他的接口大家可以举一反三，在自己实际业务情况下进行扩充，亚马逊的 Golang SDK 提供了非常全面的操作接口，全都封装在这个文件中：

...mod/github.com/aws/aws-sdk-go@v1.43.15/service/sesv2/sesv2iface/interface.go

如图所示：

亚马逊Ses API 接口

详解步骤

现在我们来逐步拆解，讲解每一步参数都是从哪里拿到的。核心的关键参数都会用黄色背景加粗展示。

登录亚马逊账号：

https://signin.aws.amazon.com/signin

在亚马逊中开通 SES 服务（强烈建议同时开通 SNS 服务，当我们发送一个邮件不成功，尤其在调试阶段，希望知道失败原因，比如模版参数不对，对方拒收等等，SES发送完之后，会通过 SNS 进行回调通知）简单地说 SES 是发邮件的， SNS是邮件发送之后的消息队列，用来推送邮件发送过程中的任何阶段结果。

Aws ses 控制台

AwsRegion：

开通完毕，我们要看一下我们开通的服务是属于哪个区，如图所示，这个就是我们在代码中要用到的 AwsRegion

Endpoint(模版发送不需要)：

指的是你要将请求发送到aws的哪个集群， SMTP 使用的必要参数，模版发送不需要，与awsRegin 配合使用的，位置如下图

Verified identities：

身份验证，这个是指我们要给用户发邮件的时候，已什么身份发，比如发给 to address： zhangsan艾特126.com， From 的邮箱身份，只有在这里配置过的，才可以放到From 里

点击右上角的 create 按照步骤一步步来即可。

Configuration sets：

配置集，直接用默认的 default 即可，在上方我提供的源码中，大家可以看到有填写配置集合的，我们可以设置多套配置，来分发不同的业务线邮件；

Configuration sets

这里有一个比较重要的概念 Event destinations 这个是关联你的SNS事件的，发送成功，失败，被拒收等等事件都可以在这里设置：

Event destinations

重要 Email Templates

这里就是核心了，不过你不能在后台直接设置，需要通过接口调用，增删改查模版的信息。

aws 模版设置

上方的代码里已经封装了模版的增改查。

Suppression list 禁止列表了解即可：

这个列表里记录的是投递之后被用户或者用户邮件服务商弹回的邮箱地址，为了提高邮件的送达率，建议开启，保持自己的“发信信誉”很重要，超量的弹回邮件，会造成你的账号信誉降低。支持手动单个、批量添加。

Cross-account notifications & Email receiving 可忽略

Cross-account notifications 跨账号通知是V1版本的功能，旧版做支持时使用；新版用的是 SNS 通知，aws 正在弃用中；不建议使用这个功能。

Email receiving 用户设置用户回信时的相关设置；推荐直接在发信时 ReplyToAddresses 填写这个 Slice，这样用户回信会直接投递到你指定的回复邮箱。

上边就是整个 SES 的配置了；

还有一个非常重要的东西 —— 身份验证： accessKey Secret

Credentials: credentials.NewStaticCredentials(accessKey, accessSecret, ""),

如下图所示，点击个人信息安全凭证，创建凭证，即可拿到属于自己的密钥对，注意保管，只显示一次。

SES邮件发送原理：

配额是你最应该注意到的坑

详细文档：
https://docs.aws.amazon.com/ses/latest/dg/quotas.html

每个邮件加上附件 base64 编码之后不能大于10M
每一封邮件的最大收件人不能超过 50人，包含（收件人、抄送、密件抄送）
每个区域中最大可以创建 10k 个邮件模板。
每个模版不能超过 500kb
每个模版可以有 [无限个] 可以替换的变量位
Ses API 的调用频率被限制在了每秒1个，所以要做好速率控制。所有操作（除了SendEmail、SendRawEmail和SendTemplatedEmail）都被限制为每秒一个请求。喜欢开协程的同学注意下，踩着点儿刹车…

参考资料：

这里的文档是帮助大家更加深入了解 SES ，以及发生错误时的排查方法。

亚马逊官方SES 文档：https://docs.aws.amazon.com/zh_cn/ses/latest/dg/send-email.html
常见错误码列表：https://docs.aws.amazon.com/ses/latest/APIReference/CommonErrors.html
SMTP 常见错误码： https://docs.aws.amazon.com/zh_cn/ses/latest/dg/troubleshoot-smtp.html

如果大家在使用中遇到问题，欢迎评论提问，我会在第一时间答复，祝大家开发顺利~

本文首发于：今日头条 —— 全栈社畜小吉 2022-09-27 00:51:25