Advanced Features

Email tracking

Email tracking helps users to collect data of 「opens」,「clicks」,「unsubscribes」 for assessment.

Users can configure 「open tracking」,「click tracking」 and 「subscribe tracking」 of an 「API_USER」 in 【delivery settings】-【tracking】. Note: 「clicking tracking」 depends on CNAME configuration of mail domain.

Address List

Address list makes it easier for users to send marketing emails. After editing/importing address list, you don’t need to add email addresses but designate the 「alias address」 of the list when calling interface.

Users can configure 「variable value」 in address list to replace the 「variable」 in 「email content」.

Users can create [address list] in 【deliveries】-【address list】.

Note:

To use address list, you are required to send emails via WEBAPI. SMTP is not support for address list.
To use address list, you are required to use 「bulk」 API_USR interface.
Only premium users are eligible for address list.

Label (label)

Label helps users to classify emails and is applicable to A/B testing.

Send emails in two styles with different labels attached, and you can know which one is more popular on the basis of opens/clicks through the labels.

Note: each email is allowed for one label.

Mail Routing

It’s exciting to receive a reply from your user. And SendCloud make it real.

With mail routing, users’ reply to an address will be send to your designated mailbox or URL for follow-up processing, and users’ email to this address will be forward to you.

Users can create mail routing though 【mail configuration】-【add mail routing】 in a domain configuration.

Subscription Relationship

Subscription relationship helps users to create and maintain the subscription relationships with customers, and build their own email subscription system.

SendCloud and ESP are actively creating subscription relationships with users, and offer strong supports to the email delivery to subscribers. (For example, QQ email list).

Customers generate a 「subscription relationship」 in SendCloud
Customers add JS code into his own website
Users visit the website, enter email address and subscribe an event
Users’ email address are added to the customers’「address list」.
Users confirm the subscription after receiving the confirmation email.
A subscription relationship between users and customer website is created.

This feature is on the basis of 「address list」. Customers need to bind this relationship to an 「address list」 when configuring subscription relationship.

Unsubscribe

When 「subscription tracking」is enabled, there will be an unsubscribe link in emails, through which recipients can unsubscribe emails.

Style of “unsubscribe” link is shown as below:

You can customize the style of “unsubscribe”, but %%user_defined_unsubscribe_link%% is required in href. Sample is as below:

You don’t need to process email specifically when default unsubscribe style is enabled; the content is as below:

<p>亲爱的%name%:</p>
<p style="margin-bottom: 35px">您好! 您本月在爱发信的消费金额为: %money% 元.</p>

Screenshot of email content is shown as below:

With customized unsubscribe enabled, email content is as below:

<p>亲爱的%name%:</p>
<p style="margin-bottom: 35px">您好! 您本月在爱发信的消费金额为: %money% 元.</p>
<p><a style="background: #1ABC9C;border:1px solid #13A386;padding:8px 20px;color: #fff;text-decoration:none;border-radius:4px" href="%%user_defined_unsubscribe_link%%">不想再收到此类邮件</a></p>

Screenshot of email content is shown as below:

WebHook

When users submit delivery request to SendCloud, 「request result」 will be simultaneously returned to users; 「delivery result」 and 「results of other event」 will be asynchronously returned to users via WebHook.

WebHook mechanism:

SendCloud provides mail events for users to choose
When an event occurs, the URL set by SendCloud will be triggered to send data (POST)
Users analyze the event and data for follow-up processing after receiving the data

Supported events are as below:

Events	Triggering Conditions
request(request)	email is successfully requested
delivered(deliver)	email is successfully sent
open(open)	user opens email
click(click)	user clicks link
unsubscribe(unsubscribe)	user unsubscribes email
spam-reporting(report_spam)	user reports email as a spam
invalid email(invalid)	email delivery failed
soft bounce(soft_bounce)	email is rejected by recipient
forwarding(route)	forward email/mail routing

Usage Method:

-Users write HTTP service to process events, analyze data and release URL
Choose interested events in 【Email】- 【Settings】-【WebHook】 and configure URL

Note: SendCloud will test users’ URL to ensure the HTTP service responds get | post request, and the returned HTTP status code is 200

Signature Verification

To ensure that the message is sent from SendCloud, you can choose to verify the source of the POST data. (You can also analyze POST data without verification)

Verification method is as below:

Acquire APP KEY in 【Delivery Settings】-【WebHook】
Analyze token, timestamp and signature in POST data
Generate signature with APP KEY, token and timestamp; check with signaturein POST data ( signature algorithm: SHA256)

python code example

import hashlib, hmac
def verify(appkey, token, timestamp, signature):
    return signature == hmac.new(
        key=appkey,
        msg='{}{}'.format(timestamp, token),
        digestmod=hashlib.sha256).hexdigest()

Java code example (dependent apache codec)

import javax.crypto.Mac;
import javax.crypto.spec.SecretKeySpec;

import org.apache.commons.codec.binary.Hex;

public boolean verify(String appkey, String token, long timestamp,
            String signature) throws NoSuchAlgorithmException, InvalidKeyException {
    Mac sha256HMAC = Mac.getInstance("HmacSHA256");
    SecretKeySpec secretKey = new SecretKeySpec(appkey.getBytes(),"HmacSHA256");
    sha256HMAC.init(secretKey);
    StringBuffer buf = new StringBuffer();
    buf.append(timestamp).append(token);
    String signatureCal = new String(Hex.encodeHex(sha256HMAC.doFinal(buf
            .toString().getBytes())));
    return signatureCal.equals(signature);
}

php code example

function verify($appkey,$token,$timestamp,$signature){
    $hash="sha256";
    $result=hash_hmac($hash,$timestamp.$token,$appkey);
    return strcmp($result,$signature)==0?1:0;
}

Event Description

Event types supported by WebHook include request, delivery, open, click, unsubscribe, spam reporting and invalid email.

Request (request)

Parameter description

parameter	type	description
event	string	event type: “request”
message	string	message content
maillistTaskId	long	task ID will be generated when you send emails with address list
mail_list_task_id	long	task ID will be generated when you send emails with address list
messageId	string	messageId
apiUser	string	API_USER
category	string	message ID
recipientArray	list	recipients
emailIds	list	emailId array
labelId	int	custom label ID
labelName	string	custom label name
recipientSize	int	count of requests
timestamp	long	timestamp
token	string	random string of 50 characters
signature	string	signature string
userHeaders	string	custom header with start of “SC-Custom”

Delivery (deliver)

Parameter description

parameter	type	description
event	string	event type: “deliver”
message	string	message content
apiUser	string	API_USER
category	string	API_USER
maillistTaskId	long	task ID will be generated when you send emails with address list
mail_list_task_id	long	task ID will be generated when you send emails with address list
emailId	string	unique ID of each email
recipient	string	recipients
labelId	int	custom label ID
labelName	string	custom label name
timestamp	long	timestamp
token	string	random string of 50 characters
signature	string	signature string
userHeaders	string	custom header with start of “SC-Custom”

Open (open)

Parameter description

parameter	type	description
event	string	event type: ”open”
message	string	message content
apiUser	string	API_USER
category	string	API_USER
maillistTaskId	long	task ID will be generated when you send emails with address list
mail_list_task_id	long	task ID will be generated when you send emails with address list
emailId	string	unique ID of each email
recipient	string	recipients
labelId	int	custom label ID
labelName	string	custom label name
ip	string	opened IP address
explorerName	string	browser name
explorerVer	string	browser version
oSName	string	OS name
oSVer	string	OS version
timestamp	long	timestamp
token	string	random string of 50 characters
signature	string	signature string
userHeaders	string	custom header with start of “SC-Custom”

Click (click)

Parameter description

parameter	type	description
event	string	event type: “type”
message	string	message content
apiUser	string	API_USER
category	string	API_USER
maillistTaskId	long	task ID will be generated when you send emails with address list
mail_list_task_id	long	task ID will be generated when you send emails with address list
emailId	string	unique ID of each email
recipient	string	recipients
labelId	int	custom label ID
labelName	string	custom label name
url	string	clicked links
ip	string	clicked IP addresses
explorerName	string	browser name
explorerVer	string	browser version
oSName	string	OS name
oSVer	string	OS version
timestamp	long	timestamp
token	string	random string of 50 characters
signature	string	signature string
userHeaders	string	custom header with start of “SC-Custom”

Unsubscribe (unsubscribe)

Parameter description

parameter	type	description
event	string	event type: ”unsubscribe”
message	string	message content
apiUser	string	API_USER
category	string	API_USER
labelId	int	custom label ID
labelName	string	custom label name
maillistTaskId	long	task ID will be generated when you send emails with address list
mail_list_task_id	long	task ID will be generated when you send emails with address list
emailId	string	unique ID of each email
recipient	string	recipients
ip	string	IP address
explorerName	string	explorer name
explorerVer	string	explorer version
oSName	string	OS name
oSVer	string	OS version
timestamp	long	timestamp
token	string	random string of 50 characters
signature	string	signature string
userHeaders	string	custom header with start of “SC-Custom”

Spam Reporting (report_spam)

Parameter description

parameter	type	description
event	string	event type: ” report_spam”
message	string	message content
apiUser	string	API_USER
category	string	API_USER
labelId	int	custom label ID
labelName	string	custom label name
emailId	string	unique ID of each email
recipient	string	recipients
timestamp	long	timestamp
token	string	random string of 50 characters
signature	string	signature string
userHeaders	string	custom header with start of “SC-Custom”

Invalid Email (invalid)

Parameter description

parameter	type	description
event	string	event type: ”invalid”
message	string	message content
apiUser	string	API_USER
category	string	API_USER
labelId	int	custom label ID
labelName	string	custom label name
maillistTaskId	long	task ID will be generated when you send emails with address list
mail_list_task_id	long	task ID will be generated when you send emails with address list
emailId	string	unique ID of each email
recipient	string	recipients
timestamp	long	timestamp
token	string	random string of 50 characters
signature	string	signature string
userHeaders	string	custom header with start of “SC-Custom”

Soft Bounce (soft_bounce)

Parameter description

parameter	type	description
event	string	event type: ” soft_bounce”
apiUser	string	API_USER
category	string	API_USER
labelId	int	custom label ID
labelName	string	custom label name
maillistTaskId	long	task ID will be generated when you send emails with address list
mail_list_task_id	long	task ID will be generated when you send emails with address list
emailId	string	unique ID of each email
recipient	string	recipients
timestamp	long	timestamp
token	string	random string of 50 characters
signature	string	signature string
userHeaders	string	custom header with start of “SC-Custom”

Mail Routing (route)

Parameter description

parameter	type	description
event	string	event type: ” soft_bounce”
from	string	sender email address
x_mx_mailfrom	string	envelope sender
fromname	string	sender name
headers	string	email headers, formatted with JSON
html	string	content in html format of routing email
message	string	message content “mx route”
raw_message_url	string	route file download. eg：`https:xxx.eml`，The link is valid for 15 days.Java parsing EML file example
raw_message	string
signature	string	signature string
subject	string	subject
text	string	content in text format of routing email
timestamp	long	timestamp
to	string	recipients address
x_mx_rcptto	string	Actual recipient address
token	string	random string of 50 characters
toname	string	recipient name
reference	string	If there is a value, the format is: 'message ID' + '@'+ 'sending domain name'
emailId	string	unique ID of each email

Experience Now

If you don’t have url to receive data,try services of requestb.in or request 纷云版 to experience WebHook.

Click Create a RequestBin to generate an url
Configure the URL in SendCloud to receive event data from WebHook
After an operation (request, deliver, open), you can see all POST data of the event in requestb.in