API Center

Quick Start

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

Authentication

All API requests require authentication through API keys.

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:

GET request example sending "helloworld" content:

POST request example sending "helloworld" content:

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

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": []
	}
}
        

MMS API

Used for batch number MMS sending, submit via POST

Request URL:

POST request example sending "helloworld" content:

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

Interface response example:

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

Voice API

1、Voice Notice

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

Request URL:

POST request example sending "helloworld" content:

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

Interface response example:

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

2、Voice OTP

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

Request URL:

POST request example sending "helloworld" content:

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

Interface response example:

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

Email API

用于发送邮件，支持POST方式提交

Request URL:

POST request example sending "helloworld" content:

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

Interface response example:

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

Webhooks

For status report push of SMS, MMS, voice and email

1、SMS Status Report Push

Used for actively pushing SMS status reports to sender, after SMS sending is completed, system actively pushes status report to sender server, sender needs to provide receiving interface URL, and reply with 200 OK response after receiving push, push method is POST.

Push URL:

Push example:

{
    "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"
        ]
    ]
}
                            

2、SMS Uplink Status Report Push

Used for actively pushing uplink status reports to sender, after terminal user replies to message, system actively pushes terminal uplink data reports to sender server, sender needs to provide receiving interface URL, and reply with 200 response after receiving push, push method is POST.

Push URL:

Push example:

{
    "fromNum": "614899xxxxx",
    "to": "614040xxxxx",
    "content": "I want it",
    "datetime": "1680278400"
}
                            

3、Voice Status Report Push

Used for actively pushing voice status reports to sender, after voice sending is completed, system actively pushes status report to sender server, sender needs to provide receiving interface URL, and reply with 200 OK response after receiving push, push method is POST.

Push URL:

Push example:

{
    "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"
        ]
    ]
}
                            

4、Email Status Report Push

Used for actively pushing email status reports to sender, after email sending is completed, system actively pushes status report to sender server, sender needs to provide receiving interface URL, and reply with 200 OK response after receiving push, push method is POST.

Push URL:

Push example:

{
	"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"
		]
	]
}
                            

5、Email Tracking Report Push

Used for actively pushing email tracking reports to sender, when users click or open, system actively pushes status report to sender server, sender needs to provide receiving interface URL, and reply with 200 OK response after receiving push, push method is POST.

Push URL:

Push example:

{
    "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"
      }
    ]
}
                            

Error Codes

Description of common error codes

1、Account Error

2、Authentication error

3、Expiration Error

4、Number Error

5、Frequency Limit

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