NotifyHub API 文档

NotifyHub 是一站式消息通知服务平台，提供统一的消息通知接口，支持短信、邮件、Push推送、语音等多种通知渠道。本文档涵盖所有 API 接口的详细说明。

快速开始

NotifyHub 提供统一的消息通知接口，支持短信、邮件、Push推送、语音等多种通知渠道。以下以短信API为例快速上手。

准备工作

1. 获取 api-token：联系接口人获取，使用时将 YOUR_API_TOKEN 替换为您的实际 Token。
2. 安装 cURL工具：确保您的系统已安装 curl 命令行工具。

步骤1：发送请求

curl -X POST https://api.notifyhub.example.com/v1/sms/send \
  -H "api-token: YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "+8613800138000",
    "content": "您的验证码是：123456，5分钟内有效。"
}'

步骤2：处理响应

{
  "success": true,
  "result": {
    "message_id": "msg_abc123456",
    "status": "queued"
  },
  "errors": []
}

身份认证

NotifyHub API 使用 api-token 进行身份认证。您需要在每个请求的 Header 中包含 api-token。

curl -X POST https://api.notifyhub.example.com/v1/sms/send \
  -H "api-token: YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"to": "+8613800138000", "content": "您的验证码是：123456"}'

• 请妥善保管您的 api-token，不要在公开场合泄露
• 如果 api-token 泄露，请及时联系我们更换
• 所有 API 请求必须使用 HTTPS 协议

1. sms/send - 发送短信

向指定手机号发送短信通知，支持单发和批量发送。

POST /v1/sms/send

参数说明

2. email/send - 发送邮件

向指定邮箱地址发送邮件通知，支持 HTML 富文本和纯文本格式。

POST /v1/email/send

参数说明

3. push/send - 发送Push通知

向指定设备或用户发送 App Push 推送通知，支持 iOS、Android 及鸿蒙平台。

POST /v1/push/send

参数说明

4. voice/call - 发送语音通知

向指定手机号发起语音电话通知，支持文本转语音（TTS）和预录音文件播报。

POST /v1/voice/call

参数说明

5. batch/send - 批量多渠道发送

在一次请求中同时向多个渠道（短信、邮件、Push）发送通知，支持按优先级自动降级。

POST /v1/batch/send

参数说明

6. message/status - 查询消息状态

根据消息ID查询消息的发送状态，支持查询短信、邮件、Push及语音的发送详情。

POST /v1/message/status

参数说明

消息状态说明：queued（排队中）、sent（已发送）、delivered（已送达）、failed（发送失败）、skipped（已跳过）

7. smart/notify - AI 智能通知（内测中）

根据用户画像和历史行为，由 AI 自动选择最佳通知渠道、时机和内容，提升通知触达率和转化率。

POST /v1/smart/notify

参数说明

8. template/list - 消息模板管理

创建、查询和管理消息模板，统一维护各渠道的通知内容。

POST /v1/template/list

参数说明

错误处理

NotifyHub API 使用标准的HTTP状态码来表示请求结果，所有响应都遵循统一的格式规范。

Serverless 接入

通过 Serverless 函数调用 NotifyHub，支持 sms.send()、email.send()、push.send()、voice.call()、batch.send() 等方法。

addEventListener('fetch', async (event) => {
    const result = await NotifyHub.sms.send({
        to: "+8613800138000",
        template_id: "tpl_verify_code",
        template_params: { code: "123456", expire: "5" }
    });
    event.respondWith(new Response(JSON.stringify(result.data), { status: 200 }));
});

Webhook 接入

NotifyHub 支持通过 Webhook 方式接入，当消息状态发生变更（送达、失败、已读等）时，系统将主动向您配置的地址推送回调通知。

在发送接口中通过 callback_url 参数指定回调地址。每次回调请求的 Header 中会携带 X-NotifyHub-Signature 签名字段，用于验证回调来源。

SDK 接入

NotifyHub 提供多语言官方 SDK，封装了鉴权、重试、错误处理等通用逻辑。

安装

# Python
pip install notifyhub-sdk

# Node.js
npm install @notifyhub/sdk

# Go
go get github.com/notifyhub/notifyhub-go

Python 示例

from notifyhub import NotifyHubClient

client = NotifyHubClient(api_token="YOUR_API_TOKEN")

# 发送短信
result = client.sms.send(
    to="+8613800138000",
    template_id="tpl_verify_code",
    template_params={"code": "123456", "expire": "5"}
)

# 发送邮件
result = client.email.send(
    to="user@example.com",
    subject="您的订单已发货",
    html="<p>您的订单已发货，请注意查收。</p>"
)

Node.js 示例

const { NotifyHubClient } = require('@notifyhub/sdk');

const client = new NotifyHubClient({ apiToken: 'YOUR_API_TOKEN' });

// 发送短信
const result = await client.sms.send({
  to: '+8613800138000',
  templateId: 'tpl_verify_code',
  templateParams: { code: '123456', expire: '5' }
});

// 发送 Push
const pushResult = await client.push.send({
  to: 'user_id_12345',
  title: '您有一条新消息',
  body: '点击查看详情'
});