SMTP通過配置項郵件標頭控制指定功能 - Direct Mail

警告

如果配置項的值設定不正確，發信會報錯，請務必經過測試後再發布到生產環境。

Direct Mail目前允許使用者通過郵件標頭X-AliDM-Settings來控制特定功能。

重要

X-AliDM-Settings 大小寫敏感，建議複製使用。

樣本：本次發信採用預設策略（對批量類型的發信地址發給特定網域名稱時）會產生退訂連結，退訂過濾層級是發信網域名稱層級。

先按照如下格式組一個JSON字串

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

對JSON字串做base64編碼

eyJWZXJzaW9uIjoiMS4wIiwiVW5zdWJzY3JpYmUiOnsiRmlsdGVyTGV2ZWwiOiJtYWlsZnJvbV9kb21haW4iLCJMaW5rVHlwZSI6InpoLWNuIn0sIk91dGJvdW5kSXAiOnsiSXBQb29sSWQiOiJ4eHgifX0=

編碼值寫入為郵件標頭X-AliDM-Settings的值。發送出郵件後，可以查看郵件標頭X-AliDM-Settings是否設定成功。

X-AliDM-Settings: eyJWZXJzaW9uIjoiMS4wIiwiVW5zdWJzY3JpYmUiOnsiRmlsdGVyTGV2ZWwiOiJtYWlsZnJvbV9kb21haW4iLCJMaW5rVHlwZSI6InpoLWNuIn0sIk91dGJvdW5kSXAiOnsiSXBQb29sSWQiOiJ4eHgifX0=

添加特殊郵件標頭，以python為例：msg.add_header("X-AliDM-Settings", Create_base64Trace)

其他語言X-AliDM-Settings值擷取方式：

Python

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"  #如果需要請在Direct Mail控制台購買獨立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)
#退訂邏輯

Java

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" #如果需要請在Direct Mail控制台購買獨立IP後，擷取IP池ID
                }
            }
            """;

        JsonElement jsonElement = JsonParser.parseString(jsonContent);
        String compactJson = new Gson().toJson(jsonElement);
        
        return Base64.getEncoder()
            .encodeToString(compactJson.getBytes(StandardCharsets.UTF_8));
    }

PHP

// 構建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"),   // 預設策略，對於到Google和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 採用預設策略：對批量類型的發信地址發給特定網域名稱時會產生退訂連結，具體參照退訂功能產生連結和過濾機制文檔 zh-cn 產生，給將來埋點到內容準備 en-us 產生，給將來埋點到內容準備
退訂功能	Unsubscribe	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