全部产品
Search
文档中心

邮件推送:SMTP通过配置项邮件头控制指定功能

更新时间:Mar 28, 2024

警告

如果配置项的值设置不正确,发信会报错,请务必经过测试后再发布到生产环境。

邮件推送目前允许用户通过邮件头X-AliDM-Settings来控制特定功能。

重要

X-AliDM-Settings 大小写敏感,建议复制使用。

示例:本次发信采用默认策略(对批量类型的发信地址发给特定域名时)会生成退订链接,退订过滤级别是发信域名级别。

  1. 先按照如下格式组一个json字符串

{"Version": "1.0", "Unsubscribe": {"LinkType": "default", "FilterLevel": "mailfrom_domain"}}
  1. 对json字符串做base64编码

eyJWZXJzaW9uIjogIjEuMCIsICJVbnN1YnNjcmliZSI6IHsiTGlua1R5cGUiOiAiZGVmYXVsdCIsICJGaWx0ZXJMZXZlbCI6ICJtYWlsZnJvbV9kb21haW4ifX0=

  1. 编码值写入为邮件头X-AliDM-Settings的值。发送出邮件后,可以查看邮件头X-AliDM-Settings是否设置成功。

X-AliDM-Settings: eyJWZXJzaW9uIjogIjEuMCIsICJVbnN1YnNjcmliZSI6IHsiTGlua1R5cGUiOiAiZGVmYXVsdCIsICJGaWx0ZXJMZXZlbCI6ICJtYWlsZnJvbV9kb21haW4ifX0=

用Java代码来表示如下:

import com.alibaba.fastjson.JSON;
import org.apache.commons.codec.binary.Base64;
import javax.mail.MessagingException;
import javax.mail.internet.MimeMessage;
import java.util.HashMap;


public class AliDMSetting {
    static public enum UnsubFilterLevel {
        DISABLED("disabled"),
        DEFAULT("default"),
        MAILFROM("mailfrom"),
        MAILFROM_DOMAIN("mailfrom_domain"),
        EDM_ID("edm_id");

        private final String value;

        UnsubFilterLevel(String value) {
            this.value = value;
        }

        public String getValue() {
            return value;
        }
    }
    static public enum UnsubLinkType {
        DISABLED("disabled"), // 不填写退订link
        DEFAULT("default"),   // 默认策略,对于到谷歌和yahoo的营销地址,启用en_US类型退订链接埋点
        ZH_CN("zh-cn"),       // 中文(简体)
        EN_US("en-us");       // 英语(美国),默认

        private final String value;

        UnsubLinkType(String value) {
            this.value = value;
        }

        public String getValue() {
            return value;
        }
    }

    public static String X_ALIDM_SETTING_HEADER_KEY = "X-AliDM-Settings";
    public static String X_ALIDM_SETTING_VERSION = "1.0";
    private UnsubLinkType unsubLinkType;
    private UnsubFilterLevel unsubFilterLevel;
    public AliDMSetting(UnsubLinkType unsubLinkType, UnsubFilterLevel unsubFilterLevel) {
        this.unsubLinkType = unsubLinkType;
        this.unsubFilterLevel = unsubFilterLevel;
    }

    private String generateHeaderValue() {
        HashMap<String,String> unsubSetting = new HashMap<String,String>();
        unsubSetting.put("LinkType", unsubLinkType.getValue());
        unsubSetting.put("FilterLevel", unsubFilterLevel.getValue());

        HashMap<String,Object> setting = new HashMap<>();
        setting.put("Version", X_ALIDM_SETTING_VERSION);
        setting.put("Unsubscribe", unsubSetting);

        return new String( Base64.encodeBase64(JSON.toJSONString(setting).getBytes()) );
    }

    public void generateHeader(MimeMessage message) throws MessagingException {
        message.addHeader(X_ALIDM_SETTING_HEADER_KEY, generateHeaderValue());
    }
}

python示例:

import json
import base64

#退订逻辑
Unsubscribe_json ={
    "Version":"1.0",
    "Unsubscribe":{
    #请根据具体需求选择参数
        # "LinkType": "disabled",
        "LinkType": "default",
        # "LinkType": "zh-cn",
        # "LinkType": "en-us",

        # "FilterLevel": "disabled",
        # "FilterLevel": "default",
        # "FilterLevel": "mailfrom",
        "FilterLevel": "mailfrom_domain"# ,
        # "FilterLevel": "edm_id"
    }
}
Unsubscribe_jsonTrace = json.dumps(Unsubscribe_json)
Unsubscribe_base64Trace = str(base64.b64encode(Unsubscribe_jsonTrace.encode('utf-8')), 'utf-8')
# print(base64Trace)
msg.add_header("X-AliDM-Settings", Unsubscribe_base64Trace)
#退订逻辑

目前已经支持的功能项如下表

功能点

配置项一级key

配置项二级key

配置项描述

退订功能

Unsubscribe

LinkType

生成的退订链接类型。参照退订功能生成链接和过滤机制文档

disabled 不生成

default 采用默认策略:对批量类型的发信地址发给特定域名时会生成退订链接,如带有关键字"gmail", "yahoo",

"google", "aol.com", "hotmail",

"outlook", "ymail.com"等

zh-cn 生成,给将来埋点到内容准备

en-us 生成,给将来埋点到内容准备

FilterLevel

过滤级别。参照退订功能生成链接和过滤机制文档

disabled 不过滤

default 采用默认策略,批量地址采用发信地址级别过滤

mailfrom 发信地址级别过滤

mailfrom_domain 发信域名级别过滤

edm_id 账号级别过滤

收件人收到的邮件头示例:

以下示例做了脱敏处理,请前往收件箱下载或查看测试邮件eml文件,获取邮件头中的退订链接。

List-Unsubscribe-Post: List-Unsubscribe=One-Click
List-Unsubscribe: <http://dm-cn.aliyuncs.com/trace/v1/unsubscribe?lang=zh-cn&sign=cd03d4d252bxxxxxxxx0d99c&token=eyJjYW1wYWlnbl90aW1lIjoxNzA2MjU3NjxxxxxxxxxxxxxxxxjAzNTUxNDMiLCJtYWlsX2Zyb20iOiJ6azFAdDEuemtkbS54eXoiLCJtYWlsX3RvIjoiemsxQHprZG0ueHl6In0%3D&version=1.0>
说明

是否显示退订按钮由收信方的策略决定,部分服务商只有发信地址或域名信誉达到要求才会显示退订按钮,建议登录收信方邮箱进行效果测试。

若还未正常显示,也可以使用下面命令对生成的链接进行测试。

linux测试命令:

以下示例做了脱敏处理,请前往收件箱下载或查看测试邮件eml文件,获取邮件头中的退订链接。

curl -X POST "http://dm-cn.aliyuncs.com/trace/v1/unsubscribe?lang=zh-cn&sign=cd03d4d252bxxxxxxxx0d99c&token=eyJjYW1wYWlnbl90aW1lIjoxNzA2MjU3NjxxxxxxxxxxxxxxxxjAzNTUxNDMiLCJtYWlsX2Zyb20iOiJ6azFAdDEuemtkbS54eXoiLCJtYWlsX3RvIjoiemsxQHprZG0ueHl6In0%3D&version=1.0"
或
curl -X POST -d "lang=zh-cn&sign=cd03d4d252bxxxxxxxx0d99c&token=eyJjYW1wYWlnbl90aW1lIjoxNzA2MjU3NjxxxxxxxxxxxxxxxxjAzNTUxNDMiLCJtYWlsX2Zyb20iOiJ6azFAdDEuemtkbS54eXoiLCJtYWlsX3RvIjoiemsxQHprZG0ueHl6In0%3D&version=1.0" "http://dm-cn.aliyuncs.com/trace/v1/unsubscribe"

效果展示:

退订测试.png