SMS Sending

send

Send a SMS template to one or more users

URL

https://api.sendcloud.net/smsapi/send

Format of returned data

json

HTTP Request Method 

POST

Parameter Description

parameter type required or not description
smsUser string yes smsUser
templateId int yes template ID
msgType int no “0”: SMS, “1”: MMS; defaults to “0”
phone string yes phone numbers of recipients, separated by commas; the amount cannot be more 2,000 each time. Contact list will be suggested when the recipients are more than 2000.
vars string no json string of substitution variable
sendRequestId string no supports up to 128 characters, multiple requests with the same sendRequestId within 1 hour will only be processed for the first time
signature string yes signature, validity verification
timestamp string no UNIX timestamp
tag string no The value is in JSON format, and the maximum character length is 128, for example: {"key1": "value1", "key2": "Value2"}

Sample of vars format:

{"name": "lucy"} or {"%money%": "100"}

Note:

  1. Variables in SMS template will be replaced by parameters in vars. All recipients users will receive the same replaced content. If the parameter content submitted by each mobile phone number is different, the interface needs to be called multiple times.Parameters in vars may contain special characters, marked with urlencode.

  2. Value of the variable is formatted with string and cannot be longer than 32 characters. HTTP links are not allowed in variables.

  3. urlencode is not required when generating signature but calling API.

sendVoice

send voice verification code

URL

https://api.sendcloud.net/smsapi/sendVoice

Format of returned data

json

HTTP Request Method

POST

Parameter Description

parameter type required or not description
smsUser string yes smsUser
phone string yes phone number of recipient
code string yes verification code
sendRequestId string no supports up to 128 characters, multiple requests with the same sendRequestId within 1 hour will only be processed for the first time
signature string yes signature, validity verification
timestamp string no Sample of code format
tag string no The value is in JSON format, and the maximum character length is 128, for example: {"key1": "value1", "key2": "Value2"}

Sample of code format:

{"code": "123456"}

Note:

  1. Parameter code is formatted with string, and consists of 4-6 numbers

sendCode (SMS template not required)

send SMS verification code

URL

https://api.sendcloud.net/smsapi/sendCode

Format of returned data

json

HTTP Request Method

POST

Parameter Description

parameter type required or not description
smsUser string yes smsUser
msgType int yes 0 represents SMS, 2 represents international SMS, default value is 0
phone string yes phone number of recipient
signId Integer * signature ID
signName string * signature name
code string yes verification code
sendRequestId string no supports up to 128 characters, multiple requests with the same sendRequestId within 1 hour will only be processed for the first time
signature string yes signature, validity verification
timestamp string no UNIX timestamp
tag string no The value is in JSON format, and the maximum character length is 128, for example: {"key1": "value1", "key2": "Value2"}

Sample of code format:

{"code": "123456"}

Note:

  1. Parameter code is formatted with string, and consists of 4-6 numbers
  2. “signId” is the ID of SMS signature. Either “signId” or “signName” is sufficient. If “signId” is not null, “signName” will be skipped.

timestamp

acquire sever timestamp

URL

https://api.sendcloud.net/smsapi/timestamp/get

Format of returned data

json

HTTP Request Method 

GET

Parameter Description

无

Return Code

Result returned from SMS API is formatted with JSON. Sample is as follows:

# 请求成功
{
    "message":"请求成功",
    "info":{"successCount":1,"smsIds":["1458113381893_15_3_11_1ainnq$131112345678"]}},
    "result":true,
    "statusCode":200
}

# 手机号格式错误
{
    "message":"手机号格式错误",
    "info":{},
    "result":false,
    "statusCode":412
}

# 部分成功
{
    "message":"部分成功",
    "info":{
            "successCount":1,
            "failedCount":1,
            "items":[{"phone":"1312222","vars":{},"message":"手机号格式错误"}],
            "smsIds":["1458113381893_15_3_11_1ainnq$131112345678"]}
            },
    "result":true,
    "statusCode":311
}
API return code meaning
200 request was successful
311 partially successful
312 all requests failed
400 duplicate request
401 SMS content cannot be empty
402 SMS content cannot exceed 500 characters
403 this interface does not support this msgType yet
404 requestId cannot be longer than 128 characters
405 requestId cannot be empty
411 phone number cannot be empty
412 invalid phone number format
413 duplicate phone numbers
414 the number of phone numbers cannot exceed 2000
415 the number of phone numbers to check cannot exceed 100 and cannot be 0
416 invalid tag format
417 tag cannot be longer than 128 characters
421 signature parameter error
422 signature error
431 template does not exist
432 template not submitted for verification or not approved
433 template ID cannot be empty
434 template type mismatch
435 template name cannot be empty
436 template name cannot exceed 64 bytes
437 template content cannot be empty
438 template content cannot exceed 512 bytes
439 MMS title cannot exceed 50 bytes
440 template content or MMS title cannot contain 【】, 测试, test characters
441 invalid substitution variable format, variable names can only contain letters, numbers and '_'
442 verification code parameter cannot be empty
443 invalid verification code parameter format
451 invalid scheduled start time format
452 scheduled start time is earlier than the server time, the time has expired
461 invalid timestamp, more than 6000 milliseconds apart from the server time
471 smsUser does not exist
472 smsUser cannot be empty
4721 smsKey cannot be empty
4722 smsUser and smsKey do not match
4723 cmpp-type smsUser cannot access HTTP interface
473 no permission, free users cannot send SMS
474 user does not exist
481 phone numbers and substitution variables cannot be empty
482 invalid format of phone numbers and substitution variables
483 substitution variable cannot be longer than 16 or 32 characters
484 links are not allowed in substitution variables
485 the number of phone numbers cannot exceed 200
491 invalid extension field ext format
496 too many messages sent to this number within one minute
497 too many messages sent to this number within five minutes
498 too many messages sent to this number in one day
499 your quota is insufficient
501 server exception
502 quota service exception, please check the request parameters
510 userId cannot be empty
601 IP access restricted, please check the IP protection (whitelist) settings
602 you do not have permission to use this interface
4340 the content corresponding to the MMS template does not exist
4393 at most 200 records can be queried
43910 template signature content cannot be empty
43911 signPositon cannot be empty
43912 invalid signPositon format
43913 isVerify cannot be empty
43914 invalid isVerify format
43915 signId cannot be empty
43916 invalid signId format
43917 enterprise verification not passed, SMS template cannot be submitted for approval
43918 invalid template ID format
43919 duplicate template name
43920 template signature can only be pure Chinese, Chinese-English mixed, Chinese-number mixed, or Chinese-English-number mixed, 2~12 characters
43921 template signature does not exist
43922 MMS content cannot be empty
43923 MMS content supports up to 50KB at most
43924 MMS content cannot be empty
43925 MMS attachment format does not conform to the specification
43926 MMS audio format does not conform to the specification
43927 MMS cannot exceed 3 pages
43928 each MMS page can contain at most one text, one picture and one audio
43929 msgType mismatch
43930 msgType cannot be empty
43931 templates pending approval cannot be edited
43932 SMS filing not passed, SMS template cannot be created yet
43940 invalid msgType format
43950 mmsType cannot be empty
43960 invalid mmsType format
43970 smsType cannot be empty
43980 invalid smsType format
7001 days or (startDate and endDate) cannot be empty
7002 invalid days format, it must be a positive integer within [1, 100] ([1, 30] for status/bounce query interfaces)
7003 invalid startDate format (e.g. '2013-03-19')
7004 invalid endDate format (e.g. '2013-03-19')
7005 startDate and endDate cannot be more than 100 days apart
70051 startDate and endDate cannot be more than 30 days apart
70052 startDate only supports dates within the previous month or the current month
7006 templateIdsStr parameter cannot be empty
7007 invalid templateIdsStr parameter format
7008 msgTypeStr cannot be empty
7009 invalid msgTypeStr parameter format
7010 invalid Aggregate parameter format
7011 invalid start parameter format
7012 invalid limit parameter format
7101 labelId cannot be empty
7102 labelId does not belong to this user
7103 labelId does not exist
7104 labelName cannot exceed 255 bytes
7105 labelName cannot be empty
7106 incorrect label type
7107 label not exceed 110000
7108 label not exceed 500000
7200 international SMS signature content cannot be pure numbers
7201 contactListName cannot be empty
7202 contactListName already exists
7203 invalid contactListName format, only English letters and numbers, no more than 24 characters
7204 description cannot exceed 100 bytes
7205 contactListName does not exist
7206 phone cannot be empty
7207 invalid phone format
7208 vars cannot be empty
7209 invalid vars format
7210 no corresponding record found
7211 taskName cannot be empty
7212 taskName cannot exceed 48 bytes
7213 senderName cannot be empty
7214 senderName cannot exceed 48 bytes
7215 taskId cannot be empty
7216 newContactListName cannot be empty
7217 invalid contactListName format, only English letters and numbers, no more than 24 characters
7218 newContactListName already exists
7219 userName cannot exceed 48 bytes
7220 invalid executeTime format
7221 signName cannot be empty
7222 invalid signName format, signature names can only be pure Chinese, Chinese-English mixed, pure English, English-number mixed, or Chinese-number mixed, 2-12 characters
7223 invalid signType format, it can only be 0 or 1
7224 signName already exists
7225 at most 10 SMS signatures can be created
7226 SMS signature ID cannot be empty
7227 the corresponding SMS signature was not found
7228 the status of this SMS signature does not allow modification
7229 SMS signature signId and signName cannot be empty at the same time
7230 the SMS signature does not match the template type
7231 qrcode does not conform to JSON specification
7232 content in qrcode cannot be empty
7233 content in qrcode cannot exceed 10KB
7234 invalid content format in qrcode
7235 type in qrcode cannot be empty
7236 invalid type format in qrcode
7237 qrcode generation error
7238 incorrect picture type format of the first MMS page when sending qrcode
7239 MMS content exceeds 50KB when sending qrcode
7240 contactListName cannot exceed 5
7241 phones list can contain no more than 100 member numbers
7242 no valid member numbers in the phones list, or the userName (if any) and vars (if any) corresponding to the phones list do not conform to the format or length limits
7243 the number of data in the phones list is not equal to the number of data in the userNames list
7244 the number of data in the phones list is not equal to the number of data in the vars list
7245 the value of parameter sendToSubscriber must be 0 or 1
7246 the value of parameter estimateSendNum must be a number
7247 parameter sendContentExample cannot exceed 512 characters at most
7248 business license not uploaded or incorrect format
7249 file upload failed
7250 an SMS template is using this signature, the signature cannot be deleted
7251 only unapproved SMS signatures can be modified
7252 invalid isThirdRights format or empty, the value can only be 0 or 1
7253 incorrect signSource
7254 supplement length should be 0-256
7255 file size cannot exceed 2MB
7256 signature already exists
7257 SMS not filed, please log in to the website to submit SMS filing
7258 signature does not match the template type
7259 signature approval not passed
7260 reply status
7261 reply status value can only be true or false
7262 reply time cannot be empty
7263 reply time can only be of long type
7264 SMS ID cannot be empty
7265 third-party legal person name cannot be empty
7266 third-party company name cannot be empty
7267 third-party company unified social credit code cannot be empty
7268 third-party agent name cannot be empty
7269 third-party agent ID number cannot be empty
7270 third-party agent phone number cannot be empty
7271 trademark certificate must be uploaded for additional pictures
101 save failed
102 update failed
103 delete failed
104 no corresponding data found
50000 API rate limited (per smsUser, per interface, no more than 4,000 calls per minute, currently only delivery responses are limited)
SMSHook error code (statusCode) meaning
410 processing failed, number is in global intercept list
420 processing failed, number is in local intercept list
430 processing failed, unsubscribe
440 processing failed, key words filtering
450 processing failed, wrong replacement variable
460 processing failed, SMS content cannot be more than 500 characters
500 SMS failure, non-existed number
510 SMS failure, number out of service
550 SMS failure, template content was complained
580 SMS failure, phone powered off
590 SMS failure, other reasons