API中心

高可用云通信API接口，低门槛接入，全球化触达

API中心

API导航

快速开始

欢迎使用 YANINGAI 云通信平台！本指南将帮助您快速开始使用我们的短信、邮件和语音服务。

第一步：注册账号

创建您的免费账号并获取 API 密钥

身份验证

所有 API 请求都需要通过 API 密钥进行身份验证。

签名鉴权

Sign签名生成方法：将登录账号、API秘钥和请求时间(秒级10位数时间戳)拼成字符串，做MD5加密，MD5使用32位小写

参数 方法 Sign
登录账号：yn00001
API密钥：7bz1lzh9
Timestamp当前系统时间戳（秒）：1630468800 		MD5(yn000017bz1lzh91630468800) 05d7a50893e22a5c4bb3216ae3396c7c

短信 API

提交短信接口，支持单个号码或多个号码发送，支持GET或POST，GET方式一次最多提交100个号码，POST方式一次最多提交50000个号码。

请求URL：

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

GET请求示例发送"helloworld"内容：

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请求示例发送"helloworld"内容：

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

注：发送号码无需带国码号，POST请求account、sign、datetime参数需放在URL中，不可放在json中提交

请求参数说明：

参数 说明 是否必填 类型
account 账号 是否必填 String
sign MD5签名(详细说明见接口说明Sign签名生成方法) 是否必填 String
datetime 需传GMT+8当前半小时内时间，格式为时间戳 是否必填 String
numbers 短信接收号码，多个号码之间以英文逗号分隔（GET请求一次最多1000个,POST请求一次最多10000个），号码无需添加国际码，注：若号码和国际码一样必须携带国际码 是否必填 String
content 短信内容 是否必填 String
codeId 见下国家码参数表 是否必填 String
action 业务类型,营销:MARKETING 验证:VERIFY 通知:NOTIFICATION 是否必填 String
senderId 发送ID，联系客服获取指定ID messages.optional String
routing 需指定通道请联系平台进行索要 messages.optional String
templateId 短信模板Id，短信模板Id和content 任选一种即可！ 是否必填 String
templateParams 模板参数,若无模板参数，则设置为空 messages.optional Array of String

接口响应示例：

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

响应参数说明：

参数 说明 类型
status 5:黑名单限制 4:国码错误 3:未找到通道 2:发送失败 1:发送成功 0:提交成功 -1:认证错误 -2:IP访问受限 -3:短信内容含有敏感字符 -4:短信内容为空 -5:短信内容过长 -6:不是模板的短信或大陆、香港、澳门、台湾方向未报备 -7:号码个数过多 -8:号码为空 -9:号码异常 -10:该通道余额不足，不能满足本次发送 -11:定时时间格式不对 -12:由于平台的原因，批量提交出错，请与管理员联系 -13:用户被锁定 -14:查询id异常 -15:请求频率过快 -16:超出时间范围限制 -17:短信模板不能为空 -18:国码ID不能为空 -19:国码ID错误 INT
message 提示信息 String
data[success] 提交成功的个数 INT
data[fail] 提交失败的个数 INT
data[batchNo] 批次号 String
data[successData] 提交成功的数据数组：号码和消息唯一ID Array
data[failData] 提交失败的数据数组：号码和消息唯一ID Array

彩信 API

用于批量号码发送彩信，POST方式提交

请求URL：

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

POST请求示例发送"helloworld"内容：

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

注：发送号码无需带国码号，POST请求account、sign、datetime参数需放在URL中，不可放在json中提交

请求参数说明：

参数 说明 是否必填 类型
account 账号 是否必填 String
sign MD5签名(详细说明见接口说明Sign签名生成方法) 是否必填 String
datetime 需传GMT+8当前半小时内时间，格式为时间戳 是否必填 String
numbers 短信接收号码，多个号码之间以英文逗号分隔（GET请求一次最多1000个,POST请求一次最多10000个），号码无需添加国际码，注：若号码和国际码一样必须携带国际码 是否必填 String
content 短信内容 是否必填 String
codeId 见下国家码参数表 是否必填 String
title 彩信主题 是否必填 String
attachment 文件附件(附件支持：[png,jpg,jpeg,bmp,gif,webp,psd,svg,tiff,mp3,wav,txt,vcf],总文件大小不超过100KB) messages.optional Array of strings<binary>
senderId 发送ID，联系客服获取指定ID messages.optional String
routing 需指定通道请联系平台进行索要 messages.optional String
templateId 短信模板Id，短信模板Id和content 任选一种即可！ 是否必填 String
templateParams 模板参数,若无模板参数，则设置为空 messages.optional Array of String

接口响应示例：

{
    "status": 0,
    "message": "提交成功",
    "data": {
        "success": 1,
        "fail": 0,
        "batchNo": "16844873111045857"
    }
}

响应参数说明：

参数 说明 类型
status 5:黑名单限制 4:国码错误 3:未找到通道 2:发送失败 1:发送成功 0:提交成功 -1:认证错误 -2:IP访问受限 -3:短信内容含有敏感字符 -4:短信内容为空 -5:短信内容过长 -6:不是模板的短信或大陆、香港、澳门、台湾方向未报备 -7:号码个数过多 -8:号码为空 -9:号码异常 -10:该通道余额不足，不能满足本次发送 -11:定时时间格式不对 -12:由于平台的原因，批量提交出错，请与管理员联系 -13:用户被锁定 -14:查询id异常 -15:请求频率过快 -16:超出时间范围限制 -17:短信模板不能为空 -18:国码ID不能为空 -19:国码ID错误 INT
message 提示信息 String
data[array] 提交成功的数据数组：号码和消息唯一ID, array[0]：唯一消息ID(string) ,array[1]：号码(string) ,array[2]：发送时间(GMT+8时区) ,array[3]：状态(int) 0：正在发送;1：发送成功;非0,1:发送失败 array[4]：状态描述(string) array[5]：批次号（string） array[6]：计费条数（string） array[7]：本条消息的扣费额度（string） Array

语音 API

1、语音通知

用于发送语音通知，可单条发送，也可批量号码发送同一内容，支持POST方式提交。

请求URL：

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

POST请求示例发送"helloworld"内容：

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

注：发送号码无需带国码号，POST请求account、sign、datetime参数需放在URL中，不可放在json中提交

请求参数说明：

参数 说明 是否必填 类型
account 账号 是否必填 String
sign MD5签名(详细说明见接口说明Sign签名生成方法) 是否必填 String
datetime 需传GMT+8当前半小时内时间，格式为时间戳 是否必填 String
numbers 短信接收号码，多个号码之间以英文逗号分隔（GET请求一次最多1000个,POST请求一次最多10000个），号码无需添加国际码，注：若号码和国际码一样必须携带国际码 是否必填 String
content 短信内容 是否必填 String
codeId 见下国家码参数表 是否必填 String
showPhone 显示号码，联系客服获取指定ID messages.optional String
routing 需指定通道请联系平台进行索要 messages.optional String
templateId 短信模板Id，短信模板Id和content 任选一种即可！ 是否必填 String
templateParams 模板参数,若无模板参数，则设置为空 messages.optional Array of String

接口响应示例：

{
    "status": 0,
    "message": "提交成功",
    "data": {
        "success": 1,
        "fail": 0,
        "barchNo": "17352639651064471"
    }
}

响应参数说明：

参数 说明 类型
status 5:黑名单限制 4:国码错误 3:未找到通道 2:发送失败 1:发送成功 0:提交成功 -1:认证错误 -2:IP访问受限 -3:短信内容含有敏感字符 -4:短信内容为空 -5:短信内容过长 -6:不是模板的短信或大陆、香港、澳门、台湾方向未报备 -7:号码个数过多 -8:号码为空 -9:号码异常 -10:该通道余额不足，不能满足本次发送 -11:定时时间格式不对 -12:由于平台的原因，批量提交出错，请与管理员联系 -13:用户被锁定 -14:查询id异常 -15:请求频率过快 -16:超出时间范围限制 -17:短信模板不能为空 -18:国码ID不能为空 -19:国码ID错误 INT
message 提示信息 String
data[success] 提交成功的个数 INT
data[fail] 提交失败的个数 INT
barchNo 批次号 String

2、语音验证码

用于发送语音验证码，一次只能提交一个号码，支持POST方式提交。

请求URL：

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

POST请求示例发送"helloworld"内容：

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

注：发送号码无需带国码号，POST请求account、sign、datetime参数需放在URL中，不可放在json中提交

请求参数说明：

参数 说明 是否必填 类型
account 账号 是否必填 String
sign MD5签名(详细说明见接口说明Sign签名生成方法) 是否必填 String
datetime 需传GMT+8当前半小时内时间，格式为时间戳 是否必填 String
numbers 短信接收号码，多个号码之间以英文逗号分隔（GET请求一次最多1000个,POST请求一次最多10000个），号码无需添加国际码，注：若号码和国际码一样必须携带国际码 是否必填 String
content 短信内容 是否必填 String
codeId 见下国家码参数表 是否必填 String
showPhone 显示号码，联系客服获取指定ID messages.optional String
routing 需指定通道请联系平台进行索要 messages.optional String
templateId 短信模板Id，短信模板Id和content 任选一种即可！ 是否必填 String
templateParams 模板参数,若无模板参数，则设置为空 messages.optional Array of String

接口响应示例：

{
    "status": 0,
    "message": "提交成功",
    "data": {
        "success": 1,
        "fail": 0,
        "array": [
            [
                "8615039xxxxxx",
                "104eadf3d9e314d8e32c18e67ae2f161"
            ]
        ]
    }
}

响应参数说明：

参数 说明 类型
status 5:黑名单限制 4:国码错误 3:未找到通道 2:发送失败 1:发送成功 0:提交成功 -1:认证错误 -2:IP访问受限 -3:短信内容含有敏感字符 -4:短信内容为空 -5:短信内容过长 -6:不是模板的短信或大陆、香港、澳门、台湾方向未报备 -7:号码个数过多 -8:号码为空 -9:号码异常 -10:该通道余额不足，不能满足本次发送 -11:定时时间格式不对 -12:由于平台的原因，批量提交出错，请与管理员联系 -13:用户被锁定 -14:查询id异常 -15:请求频率过快 -16:超出时间范围限制 -17:短信模板不能为空 -18:国码ID不能为空 -19:国码ID错误 INT
message 提示信息 String
data[success] 提交成功的个数 INT
data[fail] 提交失败的个数 INT
data['array'] 提交成功的数据数组：号码和消息唯一ID,array[0]：唯一消息ID(string) ,array[1]：号码(string) ,array[2]：发送时间(GMT+8时区) ,array[3]：状态(int) 0：正在发送;1：发送成功;非0,1:发送失败 array[4]：状态描述(string) array[5]：批次号（string） array[6]：计费条数（string） array[7]：本条消息的扣费额度（string） Array

邮件 API

messages.email_send_desc

请求URL：

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

POST请求示例发送"helloworld"内容：

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

参数 说明 是否必填 类型
account 账号 是否必填 String
sign MD5签名(详细说明见接口说明Sign签名生成方法) 是否必填 String
datetime 需传GMT+8当前半小时内时间，格式为时间戳 是否必填 String
from messages.email_from_name 是否必填 String
emails messages.email_recipients 是否必填 String
theme 邮件主题 是否必填 String
content 邮件内容 是否必填 String
attachment 文件附件 messages.optional Array of strings<binary>
placeholders 自定义变量（当内容为自定义变量定义为 {"name":"lris"},主题和内容均可定义的变量) messages.optional String(messages.json_format)
templateId 短信模板Id，短信模板Id和content 任选一种即可！ messages.optional int
routing 需指定通道请联系平台进行索要 messages.optional String

messages.response_example

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

messages.response_parameter_desc

参数 说明 类型
status 3:未找到通道 2:发送失败 1:发送成功 0:提交成功 -1:认证错误 -2:messages.ip_restricted -3:messages.missing_domain -4:邮件主题为空 -5:短信内容为空 -7:messages.too_many_emails -9:收件人为空 -10:该通道余额不足，不能满足本次发送 -11:定时时间格式不对 -14:messages.app_not_found -15:messages.request_too_fast -16:超出时间范围限制 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

参数 说明 类型
type messages.type_string String
cnt 本次推送中包含的报告条数（一个请求最多不会超多50条） 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

参数 说明 类型
fromNum messages.sender_number String
to 终端用户号码 String
content 文本内容 String
datetime GMT+8秒级时间戳 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

参数 说明 类型
type messages.type_string String
cnt 本次推送中包含的报告条数（一个请求最多不会超多50条） 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

参数 说明 类型
type messages.type_string String
cnt 本次推送中包含的报告条数（一个请求最多不会超多50条） 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

参数 说明 类型
type messages.type_string String
cnt 本次推送中包含的报告条数（一个请求最多不会超多50条） INT
array messages.array_desc Array

错误代码

用于常见错误代码的说明

1、账号错误

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

2、认证错误

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

3、失效过期

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

4、号码错误

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

5、频率限制

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

6、定时发送时区选择

注意：定时发送时区选择，例如：UTC-8 表示东八区时间，下面举例的仅为被人们熟知的地区 

UTC-12 ：扬基
UTC-11 ：萨摩亚、纽埃岛
UTC-10 ：夏威夷、夏威夷、威士忌
UTC-9:30 ：马克萨斯群岛
UTC-9 ：阿拉斯加
UTC-8 ：太平洋时间、洛杉矶、旧金山、温哥华、西雅图、拉斯维加斯
UTC-7 ：山地时间、亚利桑那、马萨特兰、凤凰城、盐湖城、丹佛、埃德蒙顿
UTC-6 ：美国和加拿大中部时间、墨西哥城、蒙特雷、芝加哥、休斯顿、新奥尔良、孟菲斯
UTC-5 ：东部时间(美国和加拿大)、哥伦比亚、多伦多、厄瓜多尔、秘鲁、古巴、纽约、汉密尔顿、圣地亚哥
UTC-4 ：委内瑞拉、玻利维亚、巴拉圭、智利
UTC-3:30 ：纽芬兰标准时间
UTC-3 ：巴西、圣地亚哥、萨尔瓦多、巴西利亚、乌拉圭、阿根廷、苏里南
UTC-2 ：南乔治亚岛、费尔南多-迪诺罗尼亚岛
UTC-1 ：佛得角、亚速尔群岛
UTC+0 ：英国、里斯本、托尔斯港、伦敦、都柏林、爱丁堡
UTC+1 ：欧洲中部、西非、中非西部、德国、爱尔兰、法国、阿姆斯特丹、意大利、柏林、罗马、西班牙、布拉格、贝尔格莱德、布鲁塞尔、巴黎、马德里、突尼斯、加蓬、摩洛哥
UTC+2 ：欧洲东部、非洲中部、土耳其、以色列、南非、伊斯坦布尔、开罗、雅典、大马士革
UTC+3 ：非洲东部、俄罗斯、巴格达、科威特、莫斯科、圣彼得堡
UTC+3:30 ：伊朗标准时间、德黑兰、马什哈德
UTC+4 ：阿布扎比、第比利斯、迪拜、毛里求斯、路易港
UTC+4:30 ：阿富汗
UTC+5 ：巴基斯坦、土库曼斯坦、马尔代夫、乌兹别克斯坦、亚美比亚、塔吉克斯坦
UTC+5:30 ：印度、孟买、新德里、班加罗尔、加尔各答
UTC+5:45 ：尼泊尔
UTC+6 ：新西伯利亚、吉尔吉斯斯坦、孟加拉国、不丹
UTC+6:30 ：澳大利亚(科科斯(基林)群岛)、缅甸
UTC+7 ：泰国、曼谷、河内、雅加达
UTC+8 ：马来西亚、菲律宾、新加坡、中国
UTC+8:45 ：中西部澳大利亚时间（欧克拉）、澳大利亚中西部时间
UTC+9 ：日本、韩国、东京、首尔、札幌、大阪、东帝汶
UTC+9:30 ：澳大利亚中部标准时间
UTC+10 ：澳大利亚、海参崴、关岛、堪培拉、墨尔本、悉尼、巴布亚新几内亚
UTC+10:30 ：澳大利亚(豪勋爵群岛*)
UTC+11 ：所罗门群岛、库页岛
UTC+12 ：新西兰、奥克兰、惠灵顿、斐济、新西兰、瑙鲁
UTC+13 ：汤加、基里巴斯
UTC+13:45 ：查塔姆岛夏令时
UTC+14 ：线岛、萨摩亚
Telegram
WhatsApp
YANINGAI企业微信二维码