API Center

Highly available cloud communication API interfaces, low-threshold access, and global reach

API中心

API Navigation

Quick Start

Welcome to YANINGAI Cloud Communication Platform! This guide will help you get started quickly with our SMS, email and voice services.

Step 1: Register Account

Create your free account and get API key

Authentication

All API requests require authentication through API keys.

Signature Authentication

Sign signature generation method: Concatenate the login account, API key, and request time (10-digit timestamp in seconds) into a string, perform MD5 encryption, using lowercase 32-bit MD5

Parameter Method Sign
Login account:yn00001
API key:7bz1lzh9
Current system timestamp (seconds):1630468800 		MD5(yn000017bz1lzh91630468800) 05d7a50893e22a5c4bb3216ae3396c7c

SMS API

Submit SMS interface, supports single or multiple number sending, supports GET or POST, maximum 100 numbers per GET request, maximum 50000 numbers per POST request.

Request URL:

http://api.yaningai.com/api/v1/sms/sendbatchsms

GET request example sending "helloworld" content:

RequestURL: http://api.yaningai.com/api/v1/sms/sendbatchsms?account=***&sign=***&datetime=***&numbers=13611111111,13722222222&content=helloworld&codeId=10007&action=MARKETING
RequestMethod: GET
RequestHeaders: Content-Type:application/json;charset=UTF-8

POST request example sending "helloworld" content:

RequestURL: http://api.yaningai.com/api/v1/sms/sendbatchsms?account=***&sign=***&datetime=***
RequestMethod: POST
RequestHeaders: Content-Type:application/json;charset=UTF-8
RequestBody: {"numbers":"13611111111,13722222222","content":"helloworld","codeId":"10007","action":"MARKETING"}

Note: Phone numbers do not need country code prefix, POST request account, sign, datetime parameters must be placed in URL, cannot be submitted in JSON

Request parameter description:

Parameter Description Required Type
account Account Required String
sign MD5 signature (see interface description for detailed explanation of Sign signature generation method) Required String
datetime Must pass GMT+8 current half-hour time, format as timestamp Required String
numbers SMS receiving numbers, multiple numbers separated by commas (maximum 1000 for GET requests, maximum 10000 for POST requests), no need to add international codes, note: if number is same as country code, must carry country code Required String
content SMS content Required String
codeId See country code parameter table below Required String
action Business type, Marketing:MARKETING Verification:VERIFY Notification:NOTIFICATION Required String
senderId Sender ID, contact customer service to obtain specified ID messages.optional String
routing To specify channel, please contact platform to request messages.optional String
templateId SMS template ID, either SMS template ID or content can be chosen! Required String
templateParams Template parameters, if no template parameters, set to empty messages.optional Array of String

Interface response example:

{
	"status": 0,
	"message": "Submit success",
	"data": {
		"success": 2,
		"fail": 0,
		"batchNo": "17585983563****",
		"successData": [{
				"phone": "6282xxxxx6504",
				"messageId": "54fc4deee43a2fecf9f2eb2e1******"
			},
			{
				"phone": "6285xxxxx8094",
				"messageId": "619586b720659816ee732050c******"
			}
		],
		"failData": []
	}
}

Response parameter description:

Parameter Description Type
status 5:Blacklist restriction 4:Country code error 3:Channel not found 2:Send failed 1:Send success 0:Submit success -1:Authentication error -2:IP access restricted -3:SMS content contains sensitive characters -4:SMS content is empty -5:SMS content too long -6:Not template SMS or mainland China, Hong Kong, Macau, Taiwan direction not registered -7:Too many numbers -8:Number is empty -9:Number abnormal -10:This channel balance is insufficient to meet this send -11:Scheduled time format incorrect -12:Due to platform reasons, batch submission error, please contact administrator -13:User locked -14:Query ID exception -15:Request frequency too fast -16:Exceeded time range limit -17:SMS template cannot be empty -18:Country code ID cannot be empty -19:Country code ID error INT
message Message String
data[success] Number of successful submissions INT
data[fail] Number of failed submissions INT
data[batchNo] Batch number String
data[successData] Successful submission data array: phone number and message unique ID Array
data[failData] Failed submission data array: phone number and message unique ID Array

MMS API

Used for batch number MMS sending, submit via POST

Request URL:

http://api.yaningai.com/api/v1/sms/mssSend

POST request example sending "helloworld" content:

RequestURL: http://api.yaningai.com/api/v1/sms/mssSend?account=***&sign=***&datetime=***
RequestMethod: POST
RequestHeaders: Content-Type:application/json;charset=UTF-8
RequestBody: {"content":"helloworld","numbers":"13611111111,13722222222","codeId":"10007","title":"hello"}

Note: Phone numbers do not need country code prefix, POST request account, sign, datetime parameters must be placed in URL, cannot be submitted in JSON

Request parameter description:

Parameter Description Required Type
account Account Required String
sign MD5 signature (see interface description for detailed explanation of Sign signature generation method) Required String
datetime Must pass GMT+8 current half-hour time, format as timestamp Required String
numbers SMS receiving numbers, multiple numbers separated by commas (maximum 1000 for GET requests, maximum 10000 for POST requests), no need to add international codes, note: if number is same as country code, must carry country code Required String
content SMS content Required String
codeId See country code parameter table below Required String
title MMS Subject Required String
attachment File attachments (supported: [png,jpg,jpeg,bmp,gif,webp,psd,svg,tiff,mp3,wav,txt,vcf], total file size not exceeding 100KB) messages.optional Array of strings<binary>
senderId Sender ID, contact customer service to obtain specified ID messages.optional String
routing To specify channel, please contact platform to request messages.optional String
templateId SMS template ID, either SMS template ID or content can be chosen! Required String
templateParams Template parameters, if no template parameters, set to empty messages.optional Array of String

Interface response example:

{
    "status": 0,
    "message": "Submit success",
    "data": {
        "success": 1,
        "fail": 0,
        "batchNo": "16844873111045857"
    }
}

Response parameter description:

Parameter Description Type
status 5:Blacklist restriction 4:Country code error 3:Channel not found 2:Send failed 1:Send success 0:Submit success -1:Authentication error -2:IP access restricted -3:SMS content contains sensitive characters -4:SMS content is empty -5:SMS content too long -6:Not template SMS or mainland China, Hong Kong, Macau, Taiwan direction not registered -7:Too many numbers -8:Number is empty -9:Number abnormal -10:This channel balance is insufficient to meet this send -11:Scheduled time format incorrect -12:Due to platform reasons, batch submission error, please contact administrator -13:User locked -14:Query ID exception -15:Request frequency too fast -16:Exceeded time range limit -17:SMS template cannot be empty -18:Country code ID cannot be empty -19:Country code ID error INT
message Message String
data[array] Successful submission data array: phone number and message unique ID, array[0]: unique message ID(string), array[1]: phone number(string), array[2]: send time(GMT+8 timezone), array[3]: status(int) 0: sending; 1: send success; non-0,1: send failure array[4]: status description(string) array[5]: batch number(string) array[6]: billing count(string) array[7]: fee deduction amount for this message(string) Array

Voice API

1、Voice Notice

Used for sending voice notifications, can send single or batch numbers with same content, support POST submission.

Request URL:

http://api.yaningai.com/api/v1/vos/notice

POST request example sending "helloworld" content:

RequestURL: http://api.yaningai.com/api/v1/vos/notice?account=***&sign=***&datetime=***
RequestMethod: POST
RequestHeaders: Content-Type:application/json;charset=UTF-8
RequestBody: {"content":"test","numbers":"13611111111,13722222222","codeId":"10007"}

Note: Phone numbers do not need country code prefix, POST request account, sign, datetime parameters must be placed in URL, cannot be submitted in JSON

Request parameter description:

Parameter Description Required Type
account Account Required String
sign MD5 signature (see interface description for detailed explanation of Sign signature generation method) Required String
datetime Must pass GMT+8 current half-hour time, format as timestamp Required String
numbers SMS receiving numbers, multiple numbers separated by commas (maximum 1000 for GET requests, maximum 10000 for POST requests), no need to add international codes, note: if number is same as country code, must carry country code Required String
content SMS content Required String
codeId See country code parameter table below Required String
showPhone Display number, contact customer service to obtain specified ID messages.optional String
routing To specify channel, please contact platform to request messages.optional String
templateId SMS template ID, either SMS template ID or content can be chosen! Required String
templateParams Template parameters, if no template parameters, set to empty messages.optional Array of String

Interface response example:

{
    "status": 0,
    "message": "Submit success",
    "data": {
        "success": 1,
        "fail": 0,
        "barchNo": "17352639651064471"
    }
}

Response parameter description:

Parameter Description Type
status 5:Blacklist restriction 4:Country code error 3:Channel not found 2:Send failed 1:Send success 0:Submit success -1:Authentication error -2:IP access restricted -3:SMS content contains sensitive characters -4:SMS content is empty -5:SMS content too long -6:Not template SMS or mainland China, Hong Kong, Macau, Taiwan direction not registered -7:Too many numbers -8:Number is empty -9:Number abnormal -10:This channel balance is insufficient to meet this send -11:Scheduled time format incorrect -12:Due to platform reasons, batch submission error, please contact administrator -13:User locked -14:Query ID exception -15:Request frequency too fast -16:Exceeded time range limit -17:SMS template cannot be empty -18:Country code ID cannot be empty -19:Country code ID error INT
message Message String
data[success] Number of successful submissions INT
data[fail] Number of failed submissions INT
barchNo Batch number String

2、Voice OTP

Used for sending voice verification codes, only one number can be submitted at a time, support POST submission.

Request URL:

http://api.yaningai.com/api/v1/vos/otp

POST request example sending "helloworld" content:

RequestURL: http://api.yaningai.com/api/v1/vos/otp?account=***&sign=***&datetime=***
RequestMethod: POST
RequestHeaders: Content-Type:application/json;charset=UTF-8
RequestBody: {"content":"test","numbers":"150xxxxxxxx","codeId":"10001"}

Note: Phone numbers do not need country code prefix, POST request account, sign, datetime parameters must be placed in URL, cannot be submitted in JSON

Request parameter description:

Parameter Description Required Type
account Account Required String
sign MD5 signature (see interface description for detailed explanation of Sign signature generation method) Required String
datetime Must pass GMT+8 current half-hour time, format as timestamp Required String
numbers SMS receiving numbers, multiple numbers separated by commas (maximum 1000 for GET requests, maximum 10000 for POST requests), no need to add international codes, note: if number is same as country code, must carry country code Required String
content SMS content Required String
codeId See country code parameter table below Required String
showPhone Display number, contact customer service to obtain specified ID messages.optional String
routing To specify channel, please contact platform to request messages.optional String
templateId SMS template ID, either SMS template ID or content can be chosen! Required String
templateParams Template parameters, if no template parameters, set to empty messages.optional Array of String

Interface response example:

{
    "status": 0,
    "message": "Submit success",
    "data": {
        "success": 1,
        "fail": 0,
        "array": [
            [
                "8615039xxxxxx",
                "104eadf3d9e314d8e32c18e67ae2f161"
            ]
        ]
    }
}

Response parameter description:

Parameter Description Type
status 5:Blacklist restriction 4:Country code error 3:Channel not found 2:Send failed 1:Send success 0:Submit success -1:Authentication error -2:IP access restricted -3:SMS content contains sensitive characters -4:SMS content is empty -5:SMS content too long -6:Not template SMS or mainland China, Hong Kong, Macau, Taiwan direction not registered -7:Too many numbers -8:Number is empty -9:Number abnormal -10:This channel balance is insufficient to meet this send -11:Scheduled time format incorrect -12:Due to platform reasons, batch submission error, please contact administrator -13:User locked -14:Query ID exception -15:Request frequency too fast -16:Exceeded time range limit -17:SMS template cannot be empty -18:Country code ID cannot be empty -19:Country code ID error INT
message Message String
data[success] Number of successful submissions INT
data[fail] Number of failed submissions INT
data['array'] Successful submission data array: phone number and message unique ID,array[0]: unique message ID(string), array[1]: phone number(string), array[2]: send time(GMT+8 timezone), array[3]: status(int) 0: sending; 1: send success; non-0,1: send failure array[4]: status description(string) array[5]: batch number(string) array[6]: billing count(string) array[7]: fee deduction amount for this message(string) Array

Email API

messages.email_send_desc

Request URL:

http://api.yaningai.com/api/v1/email/sendEmail

POST request example sending "helloworld" content:

RequestURL: http://api.yaningai.com/api/v1/email/sendEmail?account=***&sign=***&datetime=***
RequestMethod: POST
RequestHeaders: Content-Type:application/json;charset=UTF-8
RequestBody: {"emails":"xxx@163.com","from":"xxxxx","theme":"xxxxx","content":"xxxxx"}

messages.note_post_params

messages.request_parameter_desc

Parameter Description Required Type
account Account Required String
sign MD5 signature (see interface description for detailed explanation of Sign signature generation method) Required String
datetime Must pass GMT+8 current half-hour time, format as timestamp Required String
from messages.email_from_name Required String
emails messages.email_recipients Required String
theme Email subject Required String
content Email content Required String
attachment File attachments messages.optional Array of strings<binary>
placeholders Custom variables (when content is custom variable defined as {"name":"lris"}, both subject and content can define variables) messages.optional String(messages.json_format)
templateId SMS template ID, either SMS template ID or content can be chosen! messages.optional int
routing To specify channel, please contact platform to request messages.optional String

messages.response_example

{
    "status": 0,
    "message": "Submit success",
    "data": {
        "success": 1,
        "fail": 0,
        "array": [
            [
                "123@qq.com",
                "038fe903e88bbc736fcaf66e40052238"
            ]
        ]
    }
}

messages.response_parameter_desc

Parameter Description Type
status 3:Channel not found 2:Send failed 1:Send success 0:Submit success -1:Authentication Error -2:messages.ip_restricted -3:messages.missing_domain -4:Email subject is empty -5:SMS content is empty -7:messages.too_many_emails -9:Recipient is empty -10:This channel balance is insufficient to meet this send -11:Scheduled time format incorrect -14:messages.app_not_found -15:messages.request_too_fast -16:Exceeded time range limit INT
message messages.prompt_info String
data['success'] messages.success_count_desc INT
data['fail'] messages.failure_count_desc INT
data['array'] messages.success_array Array

Webhooks

messages.used_for_sms_mms_voice_email

1、messages.webhooks_sms_report

messages.webhooks_sms_desc

messages.webhooks_push_url

messages.configured_uplink_address

messages.webhooks_push_example

RequestURL: messages.configured_uplink_address
RequestMethod: POST
RequestHeaders: Content-Type:application/json;charset=UTF-8
RequestBody: 
{
    "type": "sms",
    "cnt": 2,
    "array": [
        ["48d5112288668ebb049dbb9034402910",
            "86136****1111",
            "2023-04-11T16:50:01+08:00",
            1,
            "success",
            "20221102xxxxx",
            "1",
            "0.1"
        ],
        [
            "c11d34242000e541f63fbdef3e36b1db",
            "8613722222222",
            "2023-04-11T16:51:21+08:00",
            -9,
            "number error",
            "20221102xxxxx",
            "1",
            "0.1"
        ]
    ]
}

messages.webhooks_parameter_desc

Parameter Description Type
type messages.type_string String
cnt Report count included in this push (one request will not exceed 50 reports) INT
array messages.array_desc Array

2、messages.webhooks_sms_mo_report

messages.used_for_upstream_report

messages.webhooks_push_url

messages.configured_uplink_address

messages.webhooks_push_example

RequestURL: messages.configured_uplink_address
RequestMethod: POST
RequestHeaders: Content-Type:application/json;charset=UTF-8
RequestBody: 
{
    "fromNum": "614899xxxxx",
    "to": "614040xxxxx",
    "content": "I want it",
    "datetime": "1680278400"
}

messages.webhooks_parameter_desc

Parameter Description Type
fromNum messages.sender_number String
to Terminal user number String
content Text content String
datetime GMT+8 second-level timestamp String

3、messages.webhooks_voice_report

messages.used_for_voice_report

messages.webhooks_push_url

messages.configured_uplink_address

messages.webhooks_push_example

RequestURL: messages.configured_uplink_address
RequestMethod: POST
RequestHeaders: Content-Type:application/json;charset=UTF-8
RequestBody: 
{
    "type": "vos",
    "cnt": 2,
    "array": [
        ["48d5112288668ebb049dbb9034402910",
            "86136****1111",
            "2023-04-11T16:50:01+08:00",
            1,
            "success",
            "20221102xxxxx"
        ],
        [
            "c11d34242000e541f63fbdef3e36b1db",
            "8613722222222",
            "2023-04-11T16:50:01+08:00",
            1,
            "success",
            "20221102xxxxx"
        ]
    ]
}

messages.webhooks_parameter_desc

Parameter Description Type
type messages.type_string String
cnt Report count included in this push (one request will not exceed 50 reports) INT
array messages.array_desc Array

4、messages.webhooks_email_report

messages.used_for_email_report

messages.webhooks_push_url

messages.configured_uplink_address

messages.webhooks_push_example

RequestURL: messages.configured_uplink_address
RequestMethod: POST
RequestHeaders: Content-Type:application/json;charset=UTF-8
RequestBody: 
{
	"type": "mail",
	"cnt": 2,
	"array": [
		["48d5112288668ebb049dbb9034402910",
			"123@email.com",
			"2023-04-11T16:50:01+08:00",
			1,
			"success",
			"20221102xxxxx"
		],
		[
			"c11d34242000e541f63fbdef3e36b1db",
			"456@email.com",
			"2023-04-11T16:50:01+08:00", -9,
			"email error",
			"20221102xxxxx"
		]
	]
}

messages.webhooks_parameter_desc

Parameter Description Type
type messages.type_string String
cnt Report count included in this push (one request will not exceed 50 reports) INT
array messages.array_desc Array

5、messages.webhooks_email_tracking

messages.used_for_email_tracking

messages.webhooks_push_url

messages.configured_uplink_address

messages.webhooks_push_example

RequestURL: messages.configured_uplink_address
RequestMethod: POST
RequestHeaders: Content-Type:application/json;charset=UTF-8
RequestBody: 
{
    "type": "MailUserEvent",
    "cnt": 1,
    "array": [{
      "mssId": "e904aed7624f7d349c6078f20093784f",
      "taskName": "17117048141041790",
      "domain": "frs-email.com",
      "receive_email": "110379407@qq.com",
      "time": 1711958483,
      "action_type": "OPENED",
      "country_name": "United States",
      "city": "Los Angeles",
      "device_type": "Phone",
      "device_name": "Apple"
      }
    ]
}

messages.webhooks_parameter_desc

Parameter Description Type
type messages.type_string String
cnt Report count included in this push (one request will not exceed 50 reports) INT
array messages.array_desc Array

Error Codes

Description of common error codes

1、Account Error

{"status":-1,"msg":"******"}

2、Authentication error

{"status":-1,"msg":"******"}

3、Expiration Error

{"status":-1,"msg":"******"}

4、Number Error

{"status":-9,"msg":"******"}

5、Frequency Limit

{"status":-15,"msg":"******"}

6、Timezone Selection for Scheduled Send

Note: Timezone selection for scheduled send, for example: UTC-8 represents East 8 time zone, the following examples are only well-known regions 

UTC-12 ：Yankee
UTC-11 ：Samoa, Niue
UTC-10 ：Hawaii, Hawaii, Whiskey
UTC-9:30 ：Marquesas Islands
UTC-9 ：Alaska
UTC-8 ：Pacific Time, Los Angeles, San Francisco, Vancouver, Seattle, Las Vegas
UTC-7 ：Mountain Time, Arizona, Mazatlan, Phoenix, Salt Lake City, Denver, Edmonton
UTC-6 ：US & Canada Central Time, Mexico City, Monterrey, Chicago, Houston, New Orleans, Memphis
UTC-5 ：Eastern Time (US & Canada), Colombia, Toronto, Ecuador, Peru, Cuba, New York, Hamilton, Santiago
UTC-4 ：Venezuela, Bolivia, Paraguay, Chile
UTC-3:30 ：Newfoundland Standard Time
UTC-3 ：Brazil, Santiago, Salvador, Brasilia, Uruguay, Argentina, Suriname
UTC-2 ：South Georgia, Fernando de Noronha
UTC-1 ：Cape Verde, Azores
UTC+0 ：UK, Lisbon, Tórshavn, London, Dublin, Edinburgh
UTC+1 ：Central Europe, West Africa, Western Central Africa, Germany, Ireland, France, Amsterdam, Italy, Berlin, Rome, Spain, Prague, Belgrade, Brussels, Paris, Madrid, Tunisia, Gabon, Morocco
UTC+2 ：Eastern Europe, Central Africa, Turkey, Israel, South Africa, Istanbul, Cairo, Athens, Damascus
UTC+3 ：Eastern Africa, Russia, Baghdad, Kuwait, Moscow, St. Petersburg
UTC+3:30 ：Iran Standard Time, Tehran, Mashhad
UTC+4 ：Abu Dhabi, Tbilisi, Dubai, Mauritius, Port Louis
UTC+4:30 ：Afghanistan
UTC+5 ：Pakistan, Turkmenistan, Maldives, Uzbekistan, Armenia, Tajikistan
UTC+5:30 ：India, Mumbai, New Delhi, Bangalore, Kolkata
UTC+5:45 ：Nepal
UTC+6 ：Novosibirsk, Kyrgyzstan, Bangladesh, Bhutan
UTC+6:30 ：Australia (Cocos (Keeling) Islands), Myanmar
UTC+7 ：Thailand, Bangkok, Ho Chi Minh City, Jakarta
UTC+8 ：Malaysia, Philippines, Singapore, China
UTC+8:45 ：Australian Central Western Time (Eucla), Australian Central Western Time
UTC+9 ：Japan, Korea, Tokyo, Seoul, Sapporo, Osaka, East Timor
UTC+9:30 ：Australian Central Standard Time
UTC+10 ：Australia, Vladivostok, Guam, Canberra, Melbourne, Sydney, Papua New Guinea
UTC+10:30 ：Australia (Lord Howe Island)
UTC+11 ：Solomon Islands, Sakhalin
UTC+12 ：New Zealand, Auckland, Wellington, Fiji, New Zealand, Nauru
UTC+13 ：Tonga, Kiribati
UTC+13:45 ：Chatham Island Daylight Time
UTC+14 ：Line Islands, Samoa
Telegram
WhatsApp
YANINGAI企业微信二维码