FAQ

1. What is the process of integrating SendCloud?

Registered users (50 emails/day)

Premium users (individual users, 1,000 emails/day)

Premium users (enterprise users, 3,000 emails/day)

Premium users (>6,000 emails/day)

SendCloud provides domains, API_USERs and templates for users to do testing.

2. What are the meanings of “mail_from”, “from” and “reply-to”?

mail_from: email sender, formatted with [prefix @domain]; the domain is mail domain.

from: sender in mail content; users can fill it at random, and alias supported.

If mail_from is not same as from, it means the email was 「sent for」 somebody else.

reply-to: recipient the email is replied to. reply-to is the default recipient when users reply the email directly; if not designated, recipient will be from by default.

# how to write alias
String from = MimeUtility.encodeText("爱发信客服", "UTF-8", "B") + "<support@ifaxin.com>";

3. Why is it displayed that “the email was sent for somebody else”?

mail_from and from are two different concepts, and when they don’t point to the same recipient, ESP will indicate that this email is sent for somebody else.

Sample is as follows:

pic

from = 'test@liubida.cn'
mail_from = '98a47302-beee-11e4-a3b9-00163e12fa99@push.liubida.cn'

When mail_from and from point to the same recipient, sample is as follows:

pic

However, some ESP don’t require the same recipient, but same domain such as QQ-mail box)

Prefixes in mail_from provided by SendCloud are randomly generated, and may not allowed in some ESP (it is required that mail_from must be same with from, for example, NetEase Mail).

4. Why email delivery from some domains is suspended and it is showing “emails for the domain exceeds quota” in [Deliveries – Queue Status]?

ESP provides limited mailing quota for each domain, which is called mail threshold. When emails from a domain reach the threshold, ESP will reject more requests.

We don’t know what exactly the threshold is. It is a black box data adjusted dynamically according to history data of deliveries and complaints. Based on this, SendCloud developed a custom delivery strategy (preheating delivery).

* SendCloud will estimate whether mail volume reaches the threshold based on ESP’s feedback.
* If the volume reaches threshold, emails sending to the ESP will be suspended. SendCloud will  send the rest emails at regular intervals again until the task is complete..
*Based on our experience, threshold will be reset at midnight and suspended emails will be sent automatically.
*After several preheating deliveries, threshold of the domain can be increased to meet the user’s need.
*You can send bulk emails to SendCloud at once, we will send your emails out with dynamic start-stop delivery according to the feedbacks from ESP.

Note:

ESP will adjust the threshold of a domain according to its mail quality and complaints. High mail quality and few complaints can lead to a quick increase of the threshold.

Emails sent from SendCloud are eligible for high initial threshold in ESPs in China.

Learn more about “preheat” in zhihu

5. What WebHook is for?

There will be different delivery status after an email is sent out.

For example, request was successful, email was sent successfully, email was rejected by ESP, user opened the email, user clicked the link, user unsubscribed your email.

WebHook can pull the data of the user’s behavior and POST it to your designated URL, with which you can analyze for follow-up process.

6. Will data from WebHook be lost?

If URL request error or timeout occurs, SendCloud will retry at most 5 times and the interval between is 1, 2, 4, 8, and 16 minutes, so you have at least half an hour to repair URL before the data is lost.

Once retry limit is reached, the data will be lost.

You need to return to status code 200 in three seconds when processing events and analyzing data, otherwise, SendCloud will resend the message.

7. How to use label when integrating via SMTP?

Connect label ID (label_id) to API_USER when verifying API_USER. The connection rule is as below:

api_user + '#' + label_id

Integration without label:

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

C: AUTH LOGIN base64(api_user)

Integration with label:

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

C: AUTH LOGIN base64(api_user + '#' + label_id)

Python code snippet:

# 不使用标签接入:
s = SMTP('%s:%d' % (HOST, PORT))
s.set_debuglevel(DEBUG_MODE)
if USE_SSL:
    s.starttls()
s.login(API_USER, API_KEY)

# 使用标签接入:
s = SMTP('%s:%d' % (HOST, PORT))
s.set_debuglevel(DEBUG_MODE)
if USE_SSL:
    s.starttls()
s.login(API_USER + '#' + label_id, API_KEY)

8. How to send emails by SendCloud’s client end?

Set mail sever as smtp.sendcloud.net. Account and password correspond to API_USER and API_KEY in SendCloud respectively. Below is the sample of Foxmail client:

pic

9. Is there only port 25 in SMTP service open to SendCloud users?

Considering that port 25 is forbidden by some cloud service providers, SendCloud provides port 2525 and port 587.

HOST and port numbers:

10. Confused about email template, template matching and template delivery?

Email template: simply speaking email template (template) is the predefined email content.

Template matching: before an email is sent out, SendCloud will check if the email content matches the template content. If not, users will receive an error message 553 template_validate not match, .... See template for more details.

Template delivery: With email template, users don’t need to add content after editing and uploading email template, but to designate [calling name] the template.Variable is allowed in template. The function can be realized by calling API to send emails.

It’s not allowed to use email template when sending emails via SMYP or in regular delivery.

11. Can I designate Message-ID in emails sent by SendCloud?

Yes. You can designate Message-ID in headers when sending emails via API. Sample is as below:

{
    "Message-Id": "<uuid...uuid@ifaxincom>", 
    ...
}

Note:

  1. The Message-ID is a messageId in email header but not in SendCloud system.

  2. Designated Message-ID should follow RFC specification; otherwise, there will be format detections by some ESPs.

  3. With cc, bcc and xsmtpapi extension fields, emails will be sent to multiple recipients. If you designate Message-ID, Message-IDs in all emails will be the same. So it’s not suggested.

12. Is it allowed that WebHook data contain the information I added to emails?

Yes. When you call service via API, if a Key in headers starts with “SC-Custom”, the “Key: Value” will be sent to users through WebHook. For example:

{
    "SC-Custom-key1": "value1", 
    "SC-Custom-key2": "value2", 
    ...
}

Users will receive WebHook data with the information.

pic

13. Does SendCloud support emails with embedded pictures?

It is supported by APIV2. Code example:

import requests                                                                 

url = "https://api.sendcloud.net/apiv2/mail/send"                         

API_USER = '...'
API_KEY = '...'

params = {                                                                      
    "apiUser": API_USER, # 使用api_user和api_key进行验证                       
    "apiKey" : API_KEY,                                             
    "from" : "sendcloud@sendcloud.org", # 发信人, 用正确邮件地址替代                                        
    "to" : "d@ifaxin.com", # 收件人地址, 用正确邮件地址替代, 多个地址用';'分隔                                
    "subject" : "SendCloud python embed example",                              
    "html": '<p>1st image</p> <img src="cid:image1"> <p>2nd image</p> <img src="cid:image2"/> <p>3rd image</p> <img src="cid:image1"/>',
    "embeddedCid": "image1;image2",
}                                                                               

filename1 = "/path/image1.jpg"
display_filename_1 = "image1"

filename2 = "/path/image2.jpg"
display_filename_2 = "image2"

files = [
    ("embeddedImage", (display_filename_1, open(filename1, 'rb'),'application/octet-stream')),
    ("embeddedImage", (display_filename_2, open(filename2, 'rb'),'application/octet-stream'))
]

r = requests.post(url, files=files, data=params)

print r.text

SMTP code example:

from email.mime.multipart import MIMEMultipart  
from email.mime.text import MIMEText  
from email.mime.image import MIMEImage  
import smtplib  

class MyEmail:  
    def __init__(self):  
        self.smtp = smtplib.SMTP()  
        self.login_username = 'postmaster@testdomain.sendcloud.org'
        self.login_password = '*****'  
        self.sender = 'postmaster@testdomain.sendcloud.org'    # same as login_username  
        self.receiver = 'test123@qq.com'  
        self.host = 'smtp.sencloud.net'  
        self.port = 25

    def connect(self):  
        self.smtp.connect(self.host)  

    def login(self):  
        self.smtp.login(self.login_username, self.login_password)  

    def send(self):  
        msg = MIMEMultipart('related')                 
        msg['From'] = self.sender               
        msg['To'] = self.receiver
        email_tiltle = 'python test inline image'
        msg['Subject'] = email_title           
        content = MIMEText('test image content <img src="cid:image1" alt="xxxxx">', 'html', 'utf-8')
        msg.attach(content) 

        fp = open('./test.png','rb')
        img = MIMEImage(fp.read())
        img.add_header('Content-ID','image1') #the value of content-id is the cid in html
        msg.attach(img)

        self.smtp.sendmail(self.sender, receiver, msg.as_string())   

    def quit(self):  
        self.smtp.quit()  

def send():  
    myemail = MyEmail()  
    myemail.connect()  
    myemail.login()  
    myemail.send()  
    myemail.quit()  

if __name__ == "__main__":  
    send()

14. Can I send meeting calendar with SendCloud?

Yes. You can obtain method of calling interface in [deliveries] – [send meeting calendar], which can help you to design your calendar, add meeting title, location and participant names.

Note: you need to contact customer service for permissions before using this interface. Click to view API document

15. What is email summary for and how to use it?

Email summary is an abstract of mail contents. In some superior mailbox, you can view the outline through email summary before reading the email and choose whether to open it. Content in the red box below is the email summary.

pic

Without an email summary, partial content of the email will be extracted as summary. What readers see is shown below.

pic

To better display your emails, SendCloud provides a convenient feature of sending mail summary, which has no effect on the display of original mail content. There are two ways to use this feature:

  1. Fill in email summary when editing template.

  2. Assign value to contentSummary field when using regular delivery or template delivery.

Note：

• It is suggested that the total characters of email subject and summary should be less than 60 words to avoid incomplete display.

• If the words of subject and summary is not enough, the provider will supplement it with mail content.

• Limited by different devices and mail service providers, mail summary can only display on Tencent, gmail, hotmail mailbox PC side, and it might be unsupported or incompletely displayed in other conditions.

• Test is needed to better display your emails.

16. What is the notification mechanism of SendCloud?

SendCloud provides customized notifications for you to set rules, helping you adjust email delivery strategy timely.

Notifications

pic

Notifications above have default thresholds, and will be sent to users via email by default, except for “suspended transaction emails exceed threshold”.

There are multiple notification channels to select. Email is optional to all users; WeChat is optional to bind-users; SMS is optional to premium users; email and SMS are default templates.

Verification notification

pic

Notifications above defaults to “Result Triggering”. There are multiple notification channels to select. Emails are optional to all user; WeChat is optional to bind-users; SMS is optional to premium users; email and SMS are default templates.

Notification members

Every member is allowed for 4 different phone numbers and 4 email addresses. SendCloud will notify all members by default after sending notifications.