X-SMTPAPI extended fields

X-SMTPAPI is a personalized email processing method provided by sendcloud for developers. Sendcloud 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@163.com",'i@163.com'],
    "sub": {
        "%name%": ['jack', 'rose'],
        "%money%": ['199', '299'],
    },
}

params['xsmtpapi'] = simplejson.dumps(x_smtpapi)

SMTP access：

x_smtpapi = {
    "to": ["d@163.com",'i@163.com'],
    "sub": {
        "%name%": ['jack', 'rose'],
        "%money%": ['199', '299'],
    },
}

#Custom header
msg['SC-Custom-key1'] = "value1"; 
msg['SC-Custom-key2'] = "value2";

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, sendcloud 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
5. If the customer wants to include the information buried in the email from the data of webhook, he can add a custom header when SMTP is sent. The key must start with "SC custom-", then this key:value will be returned to the user through webhook, and the key:value value value must be a string

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@ifaxin.com", "joe@ifaxin.com"]
    }

Attention:

• to here will override the recipient parameter to
• 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 ifaxin this month : %money% .

#---------------------------------------------------

# X-SMTPAPI

{
"to": ["ben@ifaxin.com", "joe@ifaxin.com"],
"sub":
{
"%name%": ["Ben", "Joe"],
"%money%":[288, 497]
}
}

#---------------------------------------------------

# ben@ifaxin.com will receive:

Dear Ben:

    Hello! Your consumption amount in ifaxin this month: 288 .

#---------------------------------------------------

# joe@ifaxin.com will receive:

Dear Joe:

    Hello! Your consumption amount in ifaxin 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 sendcloud console

• The customer needs to create a unsubscribe page in advance on the sendcloud 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 xsmt Papi. 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 under this apiuser will be used instead_ id.

Example :

x_smtpapi =
{
    "to": ["xxx@qq.com"],
    "sub":{"%name%": ["Joe"]},
    "settings": 
    {
        "unsubscribe": 
            {"page_id": 562}
    }
}