Configure links de cancelamento de inscrição e definições de IP dedicado no Direct Mail definindo o cabeçalho de mensagem SMTP X-AliDM-Settings.
Configurações incorretas causam erros na entrega de e-mails. Sempre teste as configurações antes da implantação em produção.
O cabeçalho de mensagem X-AliDM-Settings controla os recursos de cancelamento de inscrição e de IP dedicado.
X-AliDM-Settings diferencia maiúsculas de minúsculas. Copie e cole o cabeçalho para evitar erros.
O exemplo a seguir gera um link de cancelamento de inscrição filtrado no nível de domínio de e-mail para endereços de remetente em lote.
Crie uma string JSON no seguinte formato:
{"Version":"1.0","Unsubscribe":{"FilterLevel":"mailfrom_domain","LinkType":"zh-cn"},"OutboundIp":{"IpPoolId":"xxx"}}Codifique a string JSON em Base64.
eyJWZXJzaW9uIjoiMS4wIiwiVW5zdWJzY3JpYmUiOnsiRmlsdGVyTGV2ZWwiOiJtYWlsZnJvbV9kb21haW4iLCJMaW5rVHlwZSI6InpoLWNuIn0sIk91dGJvdW5kSXAiOnsiSXBQb29sSWQiOiJ4eHgifX0=Defina a string codificada como valor do cabeçalho X-AliDM-Settings. Após o envio, verifique o cabeçalho na mensagem recebida.
X-AliDM-Settings: eyJWZXJzaW9uIjoiMS4wIiwiVW5zdWJzY3JpYmUiOnsiRmlsdGVyTGV2ZWwiOiJtYWlsZnJvbV9kb21haW4iLCJMaW5rVHlwZSI6InpoLWNuIn0sIk91dGJvdW5kSXAiOnsiSXBQb29sSWQiOiJ4eHgifX0=Exemplo em Python: msg.add_header("X-AliDM-Settings", Create_base64Trace)
Gere o valor de X-AliDM-Settings em outras linguagens:
import json
import base64
# Unsubscribe logic
Create_json = {
"Version" : "1.0",
"Unsubscribe" : {
# Select parameters as needed.
# "LinkType": "disabled", # Do not generate an unsubscribe message header.
"LinkType": "default", # Default policy, which enables instrumentation for en-us unsubscribe links.
# "FilterLevel": "disabled", # Do not filter.
# "FilterLevel": "default", # Default policy, which filters batch addresses at the sender address level.
# "FilterLevel": "mailfrom", # Filter at the sender address level.
"FilterLevel": "mailfrom_domain" # Filter at the email domain level.
# "FilterLevel": "edm_id" # Filter at the account level.
},
"OutboundIp" : {
"IpPoolId" : "exxxxxxe-4xx0-4xx3-8xxa-7xxxxxxxxxxxxf" # If needed, purchase a dedicated IP address in the Direct Mail console and obtain the IP pool 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)
# Unsubscribe logicimport 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", // Default policy, which enables instrumentation for en-us unsubscribe links.
"FilterLevel": "mailfrom_domain" // Filter at the email domain level.
},
"OutboundIp": {
"IpPoolId": "exxxxxxe-4xx0-4xx3-8xxa-7xxxxxxxxxxxxf" // If needed, purchase a dedicated IP address in the Direct Mail console and obtain the IP pool ID.
}
}
""";
JsonElement jsonElement = JsonParser.parseString(jsonContent);
String compactJson = new Gson().toJson(jsonElement);
return Base64.getEncoder()
.encodeToString(compactJson.getBytes(StandardCharsets.UTF_8));
}// Build the JSON.
$createJson = [
"Version" => "1.0",
"Unsubscribe" => [
"LinkType" => "default", // Default policy.
"FilterLevel" => "mailfrom_domain" // Filter at the email domain level.
],
"OutboundIp" => [
"IpPoolId" => "exxxxxxe-4xx0-4xx3-8xxa-7xxxxxxxxxxxxf" // Replace with your IP pool ID.
]
];
// Convert to a JSON string.
$jsonString = json_encode($createJson, JSON_UNESCAPED_SLASHES | JSON_UNESCAPED_UNICODE);
// Base64 encode.
$base64Trace = base64_encode($jsonString);
// Add a custom message header.
$mail->addCustomHeader('X-AliDM-Settings', $base64Trace);Segundo exemplo em Java:
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"), // Do not add an unsubscribe link.
DEFAULT("default"), // Default policy. For marketing emails sent to Google and Yahoo addresses, enable instrumentation for en_US unsubscribe links.
ZH_CN("zh-cn"), // Chinese (Simplified)
EN_US("en-us"); // English (US), 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;
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());
}
}Recursos compatíveis:
|
Recurso |
Chave de primeiro nível |
Chave de segundo nível |
Descrição |
|
Cancelamento de inscrição |
Unsubscribe |
LinkType |
Tipo de link de cancelamento de inscrição a gerar.
|
|
FilterLevel |
Nível de filtragem aplicado.
|
||
|
IP dedicado |
OutboundIp |
IpPoolId |
ID do pool de IPs dedicados. Roteia e-mails de saída pelo endereço IP dedicado adquirido. |
Exemplo de cabeçalho recebido pelo destinatário:
O exemplo abaixo foi redigido. Baixe ou visualize o arquivo .eml para ver o link real de cancelamento de inscrição.
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>O cabeçalho List-Unsubscribe-Post: List-Unsubscribe=One-Click habilita o cancelamento de inscrição com um clique:
Com esse cabeçalho, a ação de cancelamento é concluída via HTTP POST sem confirmação do usuário.
Sem esse cabeçalho ou com um valor fora do padrão, o processo de cancelamento pode recorrer a
mailto:ou redirecionamento de link, exigindo confirmação manual.A exibição do botão depende do provedor de e-mail do destinatário. Alguns provedores exigem boa reputação do endereço ou domínio do remetente. Acesse a caixa de correio do destinatário para verificar.
Se o botão não aparecer, teste o link gerado com o comando a seguir.
Comando de teste no Linux:
O exemplo abaixo foi redigido. Baixe ou visualize o arquivo .eml para ver o link real de cancelamento de inscrição.
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"Resultado do exemplo:
