X-SMTPAPI Extended Fields
X-SMTPAPI is a personalized email processing method provided by EngageLab for developers.
EngageLab will retrieve the header field information with key as X-SMTPAPI
. If it is found to contain this header field, it will parse the value of value to change the mail processing method. Developers can use this field when using SMTP and API access.
API access:
x_smtpapi = {
"to": ["d@hotmail.com",'i@hotmail.com'],
"sub": {
"%name%": ['jack', 'rose'],
"%money%": ['199', '299'],
},
}
params['xsmtpapi'] = simplejson.dumps(x_smtpapi)
SMTP access:
x_smtpapi = {
"to": ["d@hotmail.com",'i@hotmail.com'],
"sub": {
"%name%": ['jack', 'rose'],
"%money%": ['199', '299'],
},
}
msg['X-SMTPAPI'] = Header(base64.b64encode(simplejson.dumps(x_smtpapi)))
The SMTP server will check the format of the header information with **key** as `X-SMTPAPI`in the email. If the above requirements are not met, an error of `xsmtpapi error` will be reported.
It should be noted that:
1. When calling SMTP, the X-SMTPAPI must be the last one in the header field. Otherwise, an error of 'xsmtpapi error' may be caused
2. When calling SMTP, the x-smtpapi must be Base64 encoded. Otherwise, after the successful SMTP request, EngageLab intercepts and judges the mail as invalid - ` worker: invalid XSMTP-API '
3. When calling API, you can directly pass in the JSON string without Base64 encoding and encapsulation
4. The total length of X-SMTPAPI cannot exceed 1m
The structure and use of the JSON string encapsulated by value are shown below :
to
Contains an array of recipient addresses to specify the recipients of the message.
{
"to": ["ben@engagelab.com", "joe@engagelab.com"]
}
Attention:
to
here will override the recipient parameterto
- The number of
to
recipients here cannot exceed 100
Sub
is an associative array** its key
is a variable' and value
is a 'replacement value array'
Usage explanation: each "variable" corresponds to a "replacement value array". When replacing the contents of e-mail, each "Recipient" replaces the value of "variable" with the corresponding value in the "replacement value array" according to its position in the "recipient array"
Example :
# Email content
Dear %name%:
Hello! Your consumption amount in XX this month : %money% .
#---------------------------------------------------
# X-SMTPAPI
{
"to": ["ben@engagelab.com", "joe@engagelab.com"],
"sub":
{
"%name%": ["Ben", "Joe"],
"%money%":[288, 497]
}
}
#---------------------------------------------------
# ben@engagelab.com will receive:
Dear Ben:
Hello! Your consumption amount in XX this month: 288 .
#---------------------------------------------------
# joe@engagelab.com will receive:
Dear Joe:
Hello! Your consumption amount in XX this month: 497 .
apps
is an associative array containing a set of application names (Unsubscribe, Open, Click) and their settings** . These settings override their settings in the user account
x_smtpapi =
{
"to": ["xxx@qq.com"],
"sub": {"%name%": ["Joe"]},
"filters": {
"subscription_tracking": { # Unsubscribe tracking
"settings": { "enable": "1" }
},
"open_tracking": { # Open tracking
"settings": { "enable": "1" }
},
"click_tracking": { # Click tracking
"settings": { "enable": "1" }
}
}
}
page_id
- Page_id corresponds to the ID field of a unsubscribe page created under "Setting" - "Unsubscribe" - "Unsubscribe page" in EngageLab console
- The customer needs to create a unsubscribe page in advance on the EngageLab console before sending it to the page_ Set the ID to the corresponding ID
- Send via page_ID parameter. The value is set as the ID of a unsubscribe page. At this time, the unsubscribe link and unsubscribe page are in the configured language and style
- The priority of page_id parameter transmission is higher than that of API at the time of transmission_ The default unsubscribe page setting corresponding to user
- Support the array form to specify the unsubscribe page, which should be consistent with the number of to in the xsmtpapi. The array position corresponds to each "Recipient" according to its position in the "recipient array". If it does not match the number of to, the default page_id under this apiUser will be used instead.
Example :
x_smtpapi =
{
"to": ["xxx@qq.com", "xxx@hotmail.com", "xxx@gmail.com"],
"sub":{"%name%": ["Joe", "Ben", "Michael"]},
"settings":
{
"unsubscribe":
{"page_id": [1, 2, 3]}
}
}