AI 助理
备案控制台
官方文档
输入文档关键字查找
首页 邮件推送 SMTP 参考 SMTP高阶功能 SMTP通过配置项邮件头控制指定功能

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

更新时间：
产品详情
我的收藏
重要

本文中含有需要您注意的重要提示信息，忽略该信息可能对您的业务造成影响，请务必仔细阅读。

警告

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

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

重要

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

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

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

{"Version":"1.0","Unsubscribe":{"FilterLevel":"mailfrom_domain","LinkType":"zh-cn"},"OutboundIp":{"IpPoolId":"xxx"}}

  1. 对JSON字符串做base64编码

eyJWZXJzaW9uIjoiMS4wIiwiVW5zdWJzY3JpYmUiOnsiRmlsdGVyTGV2ZWwiOiJtYWlsZnJvbV9kb21haW4iLCJMaW5rVHlwZSI6InpoLWNuIn0sIk91dGJvdW5kSXAiOnsiSXBQb29sSWQiOiJ4eHgifX0=

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

X-AliDM-Settings: eyJWZXJzaW9uIjoiMS4wIiwiVW5zdWJzY3JpYmUiOnsiRmlsdGVyTGV2ZWwiOiJtYWlsZnJvbV9kb21haW4iLCJMaW5rVHlwZSI6InpoLWNuIn0sIk91dGJvdW5kSXAiOnsiSXBQb29sSWQiOiJ4eHgifX0=

添加特殊邮件头 ，以python为例：msg.add_header("X-AliDM-Settings", Create_base64Trace)

其他语言X-AliDM-Settings值获取方式：

import json
import base64

#退订逻辑
Create_json = {
    "Version" : "1.0",
    "Unsubscribe" : {
    #请根据具体需求选择参数
        # "LinkType": "disabled",  #不生成退订邮件头
        "LinkType": "default", # 默认策略，启用en-us类型退订链接埋点

        # "FilterLevel": "disabled", #不过滤
        # "FilterLevel": "default", #采用默认策略，批量地址采用发信地址级别过滤
        # "FilterLevel": "mailfrom", #发信地址级别过滤
        "FilterLevel": "mailfrom_domain" #发信域名级别过滤
        # "FilterLevel": "edm_id" #账号级别过滤
    },
    "OutboundIp" : {
        "IpPoolId" : "exxxxxxe-4xx0-4xx3-8xxa-7xxxxxxxxxxxxf"  #如果需要请在邮件推送控制台购买独立IP后，获取IP池ID
    }
}
Create_jsonTrace = json.dumps(Create_json)
Create_base64Trace = str(base64.b64encode(Create_jsonTrace.encode('utf-8')), 'utf-8')
# print(base64Trace)
msg.add_header("X-AliDM-Settings", Create_base64Trace)
#退订逻辑
import java.util.Base64;
import com.google.gson.Gson;
import com.google.gson.JsonElement;
import com.google.gson.JsonParser;
import java.nio.charset.StandardCharsets;

private static String generateDmSettingsHeader() {
        String jsonContent = """
            {
                "Version": "1.0",
                "Unsubscribe": {
                    "LinkType": "default", // 默认策略，启用en-us类型退订链接埋点
                    "FilterLevel": "mailfrom_domain" //发信域名级别过滤
                },
                "OutboundIp": {
                    "IpPoolId": "exxxxxxe-4xx0-4xx3-8xxa-7xxxxxxxxxxxxf" #如果需要请在邮件推送控制台购买独立IP后，获取IP池ID
                }
            }
            """;

        JsonElement jsonElement = JsonParser.parseString(jsonContent);
        String compactJson = new Gson().toJson(jsonElement);
        
        return Base64.getEncoder()
            .encodeToString(compactJson.getBytes(StandardCharsets.UTF_8));
    }
// 构建JSON
	$createJson = [
		"Version" => "1.0",
		"Unsubscribe" => [
			"LinkType" => "default",       // 默认策略
			"FilterLevel" => "mailfrom_domain" // 发信域名级别过滤
		],
		"OutboundIp" => [
			"IpPoolId" => "exxxxxxe-4xx0-4xx3-8xxa-7xxxxxxxxxxxxf" // 替换为你的IP池ID
		]
	];

	// 转换为JSON字符串
	$jsonString = json_encode($createJson, JSON_UNESCAPED_SLASHES | JSON_UNESCAPED_UNICODE);

	// Base64编码
	$base64Trace = base64_encode($jsonString);

	// 添加自定义邮件头
	$mail->addCustomHeader('X-AliDM-Settings', $base64Trace);

java 示例2：

package ut_dm;

import com.alibaba.fastjson.JSON;
import org.apache.commons.codec.binary.Base64;
import org.apache.commons.lang3.StringUtils;

import javax.mail.MessagingException;
import javax.mail.internet.MimeMessage;
import java.util.HashMap;
import java.util.Map;


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;
    private String ipPoolId;
    public AliDMSetting(UnsubLinkType unsubLinkType, UnsubFilterLevel unsubFilterLevel, String ipPoolId) {
        this.unsubLinkType = unsubLinkType;
        this.unsubFilterLevel = unsubFilterLevel;
        this.ipPoolId = ipPoolId;
    }

    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);
        if(StringUtils.isNotBlank(ipPoolId)) {
            Map<String, String> outboundIpsMap = new HashMap<>();
            outboundIpsMap.put("IpPoolId", ipPoolId);
            setting.put("OutboundIp", outboundIpsMap);
        }

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

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

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

功能点

配置项一级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 账号级别过滤

独立IP功能

OutboundIp

IpPoolId

独立IP地址池ID。购买了独立IP的用户可以通过这个参数指定发信出口IP。

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

以下示例做了脱敏处理，请前往收件箱下载或查看测试邮件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>
说明

List-Unsubscribe-Post: List-Unsubscribe=One-Click用于控制是否一键退订。

  • 功能：声明邮件支持“一键退订”（通过HTTP POST请求直接完成退订，无需用户二次确认）。

  • 非标准值或无值：若省略该头部或使用其他值（如空值），则退订流程可能回退到传统的mailto:或链接跳转方式（需用户手动确认）。

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

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

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

如何使用自己的退订邮箱或退订链接？

SMTP发信时，添加自定义头，需要提前准备退订邮箱或退订链接，例（python）：msg['List-Unsubscribe'] = '<mailto:unsubscribe@example.com>,<https://example.com/unsubscribe>'。

自定义退订信息会覆盖系统默认的退订链接，并且无需再次传入"X-AliDM-Settings"。

相关文档：独立 IP

上一篇：SMTP发信支持按照Tag埋点统计打开邮件数据下一篇：SMTP多线程发信示例之Python