General Rules

SMTP request methods

A method to provide SMTP protocol for developers. Dialogue is as follows. For detailed code example, navigate HRER

S: 220 SendCloud Inbound Server ESMTP Haraka 2.2.4 ready

C: ehlo ifaxin.com

S: 250-SendCloud Inbound Server Hello, Haraka is at your service.
S: 250-PIPELINING
S: 250-8BITMIME
S: 250-SIZE 16000000
S: 250 AUTH LOGIN

C: AUTH LOGIN base64(api_user)

S: 334 UGFzc3dvcmQ6

C: base64(api_key)

S: 235 Authentication successful

C: mail FROM:<support@ifaxin.com>

S: 250 sender <support@ifaxin.com> OK

C: rcpt TO:<ben@ifaxin.com>

S: 250 recipient <ben@ifaxin.com> OK

C: data

S: 354 go ahead, make my day

C: ... ...
C: .

S: 250 #1426390015358_15_6484_8661.sc-10_10_127_51-inbound#Queued

C: quit

S: 221 SendCloud Inbound Server closing connection. Have a jolly good day

messageId and emailId

messageId is a message number returned after submitting a request.

emailId is an email number returned after SendCloud sends an email. It can be corresponded to a certain recipient of a certain request.

Calculation formula:

to = [A, B, C]
emailId_A = messageId + to.index(A) + '$' + A
emailId_B = messageId + to.index(B) + '$' + B
emailId_C = messageId + to.index(C) + '$' + C

# 注意: position 不做位数补齐

Example is as below:

# to = ["ben@ifaxin.com", "joe@ifaxin.com", "bida@ifaxin.com", ... , "lianzimi@ifaxin.com"]
1425758592214_4576_32113_9310.sc-10_10_127_105-inbound  # messageId
1425758592214_4576_32113_9310.sc-10_10_127_105-inbound0$ben@ifaxin.com  # emailId
1425758592214_4576_32113_9310.sc-10_10_127_105-inbound1$joe@ifaxin.com  # emailId
1425758592214_4576_32113_9310.sc-10_10_127_105-inbound2$bida@ifaxin.com  # emailId
...
1425758592214_4576_32113_9310.sc-10_10_127_105-inbound99$lianzimi@ifaxin.com  # emailId

maillistTaskId

When sends emails with address list, SendCloud will asynchronously call backend services to deliver emails. You will receive maillistTaskId returned from SendCloud API, with which you can query data of the address list.

X-SMTPAPI

X-SMTPAPI is for developers to customize emails and set various parameters. It is available when developers access via both SMTP and API .

SendCloud will retrieve header fields with X-SMTPAPI, once found, its value will be parsed to change the mail-processing mode.

API：code_example - send with xsmtpapi

sub personalized template variable allows each recipient to receive customized email content based on their specific replacement value.

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

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

pubsub common template variable, all recipients receive the same replaced content

x_smtpapi = {
    "to": ["d@163.com", "i@163.com"],
    "pubsub": {
        "%productName%": "华为手表",
        "%discountedPrice%": 1989.0
        "%discount%": "8.5"
    }
}

#OR:
x_smtpapi = {
    "pubsub": {
        "%productName%": "华为手表",
        "%discountedPrice%": 1989.0
        "%discount%": "8.5"
    }
}

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

Note: Pubsub has a higher priority than sub. If both Pubsub and sub are passed simultaneously, sub will be ignored.

SMTP：code_example - SMTP

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

#OR：
x_smtpapi = {
    "to": ["d@163.com", "i@163.com"],
    "pubsub": {
        "%productName%": "华为手表",
        "%discountedPrice%": 1989.0
        "%discount%": "8.5"
    }
}

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

msg['X-SMTPAPI'] = Header(base64.b64encode(simplejson.dumps(x_smtpapi)))

Note:

The SMTP server will check the format of the header information with key as X-SMTPAPIin 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 6. Pubsub has a higher priority than sub. If both Pubsub and sub are passed simultaneously, sub will be ignored.

Structure and usages of value are as follows:

to contains the array of recipient, recipient of specified email.

    {
        "to": ["ben@ifaxin.com", "joe@ifaxin.com"]
    }

Note:

sub is an associative array with its key as「variable」, and value as「replacement value array」.

Usage description: Each 「variable」corresponds to a 「replacement value array」. When replacing mail content, each 「recipient」 replaces 「variable」 value with the value of 「replacement」 value array」in corresponding position to where 「recipient」 appears in 「recipient array」.

See example below:

# 邮件内容
亲爱的%name%:

    您好! 您本月在爱发信的消费金额为: %money% 元.

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

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

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

# ben@ifaxin.com 收到的邮件:
亲爱的Ben:

    您好! 您本月在爱发信的消费金额为: 288 元.

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

# joe@ifaxin.com 收到的邮件:
亲爱的Joe:

    您好! 您本月在爱发信的消费金额为: 497 元.

apps is an associative array containing a set of application names and settings. The settings will overlay settings in user account.

{
   "......",
   "filters": {
        "subscription_tracking": { # 退订追踪
            "settings": { "enable": "1" }
        },
        "open_tracking": { # 打开追踪
            "settings": { "enable": "1" }
        },
        "click_tracking": { # 点击追踪
            "settings": { "enable": "1" }
        }
    }
}

page_id

Usage explanation:

  1. page_ ID corresponds to the ID field of a unsubscribe page created under "发送设置" - "退订设置" - "退订页面" in sendcloud console.
  2. 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.
  3. 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.
  4. page_ The priority of ID parameter transfer is higher than that of API when sending_ The default unsubscribe page setting corresponding to user.

Examples:

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