Configure the Message Header to Control the Specified Function for SMTP Sending Method - Direct Mail

Direct Mail currently allows user to control specific features through X-AliDM-Settings of message header.

Warning

If the value of the configuration items is not set correctly, an error will be reported in the message. You must test the message first and then publish it to your production environment.

Example: This email sending needs to generate an unsubscription link on the default strategy (When sending batch address to specific domain names), and the unsubscription filter level is the sending domain name level.

1. First, group a JSON string in the following format;

{"Version": "1.0", "Unsubscribe": {"LinkType": "default", "FilterLevel": "mailfrom_domain"}}

2. Encode the JSON string in Base64;

eyJWZXJzaW9uIjogIjEuMCIsICJVbnN1YnNjcmliZSI6IHsiTGlua1R5cGUiOiAiZGVmYXVsdCIsICJGaWx0ZXJMZXZlbCI6ICJtYWlsZnJvbV9kb21haW4ifX0=

2. The encoded value is written as the value of the X-AliDM-Settings of message header. You can check whether the X-AliDM-Settings of message header is set after sending.

X-AliDM-Settings: eyJWZXJzaW9uIjogIjEuMCIsICJVbnN1YnNjcmliZSI6IHsiTGlua1R5cGUiOiAiZGVmYXVsdCIsICJGaWx0ZXJMZXZlbCI6ICJtYWlsZnJvbV9kb21haW4ifX0=

This is expressed in Java code as follows:

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"), // The unsubscription link is not specified.
        DEFAULT("default"), // The default policy. For marketing addresses to Google and Yahoo, enable the en_US type unsubscribe link tracking point
        ZH_CN("zh-cn"), // Chinese (Simplified)
        EN_US("en-us"); // English (the United States), default

        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());
    }
}

This is expressed in Python code as follows:

import json
import base64

#The Unsubscription Logic
Unsubscribe_json ={
 "Version":"1.0",
 "Unsubscribe":{
 #Please select the parameter based on the specific needs.
 # "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)
#The Unsubscription Logic

The following table lists the supported features:

Features

Configuration Items Level -1 Key

Configuration Items

Level -2 Key

Description

Unsubscription Function

Unsubscribe

LinkType

The type of the generated unsubscription link. For more information, please refer to The Description of the Unsubscription Function.

disabled is not generated.

default uses the default policy: An unsubscription link is generated when the batch type of sender addresses send to a specific domain, such as Gmail, Yahoo, Google, aol.com, Hotmail, Outlook and Ymail.com.

zh-cn is generated, for implement tracking to content preparation in the future.

en-us is generated, for implement tracking to content preparation in the future.

FilterLevel

The filter level. For more information, please check The Description of the Unsubscription Function.

disabled is not filtered

default uses the default policy: The batch type of sending addresses are filtered at the sending address level.

mailfrom: sending address level filtering

mailfrom_domain: sending domain-level filtering

edm_id: account-level filtering

Examples of headers received by recipients:

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

Note

Whether to display the unsubscription button is determined by the recipient's policy. It is recommended to login to the recipient's mailbox to test the effect.

In special cases, you can also use the following command to test the generated links.

Linux test commands:

Please replace the link with the actual unsubscription link.

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

Effect Display