消息推送 API
统一消息面:消息提供商(provider:邮件/短信/推送通道)、主题(topic)与订阅者(subscriber)、草稿与排期消息(email / sms / push)的创建、修改与投递日志。
服务与资源边界
消息推送 API(/v1/messaging/*)提供跨通道(邮件 Email、短信 SMS、移动端推送 Push)的统一通知编排与投递审计能力:支持配置多厂商通道提供商(SMTP / SendGrid / Mailgun / Resend、Twilio / Vonage / Telesign / MSG91 / TextMagic、APNs / FCM),通过主题(Topic)、用户 ID(User)与设备目标(Target)三层寻址模型组合圈定收件人,并支持草稿(Draft)保存、定时排期(scheduledAt)发送与投递日志追踪。
资源与基础路径
Base URL:
https://<your-endpoint>/v1,路径前缀/messaging。资源:
provider({providerId})、topic({topicId})、subscriber({subscriberId})、message({messageId})。收件人解析:消息可同时指定
topics(主题)、users(用户,自动解析其 target)、targets(精确目标);三者可组合。
认证与权限
认证与请求头约定见 通用约定。本域 scope:messages.read / messages.write(消息)、providers.read / providers.write(提供商)、topics.read / topics.write(主题)、subscribers.read / subscribers.write(订阅者)。
端点总览
Messaging 模块共包含 46 个端点,按资源划分为三大组:消息创建(Email / SMS / Push)、草稿更新、删除与投递目标/日志查询(11 个);三类通道共 11 种上游提供商(Providers)的专项创建、更新與管理端点(25 个);主题(Topics)与订阅者(Subscribers)管理端点(10 个)。
端点清单
消息(messages)
| 方法 + 路径 | 用途 |
|---|---|
GET /messaging/messages | 列出消息 |
POST /messaging/messages/email | 创建邮件 |
PATCH /messaging/messages/email/{messageId} | 更新邮件 |
POST /messaging/messages/sms | 创建短信 |
PATCH /messaging/messages/sms/{messageId} | 更新短信 |
POST /messaging/messages/push | 创建推送通知 |
PATCH /messaging/messages/push/{messageId} | 更新推送通知 |
GET /messaging/messages/{messageId} | 获取消息 |
DELETE /messaging/messages/{messageId} | 删除消息 |
GET /messaging/messages/{messageId}/targets | 消息解析出的目标列表 |
GET /messaging/messages/{messageId}/logs | 消息投递日志 |
提供商(providers)
| 方法 + 路径 | 用途 |
|---|---|
GET /messaging/providers | 列出提供商 |
POST /messaging/providers/apns|fcm | 创建推送提供商(APNS / FCM) |
POST /messaging/providers/mailgun|sendgrid|smtp|resend | 创建邮件提供商 |
POST /messaging/providers/twilio|vonage|telesign|msg91|textmagic | 创建短信提供商 |
PATCH /messaging/providers/{type}/{providerId} | 更新对应类型提供商 |
GET /messaging/providers/{providerId} | 获取提供商 |
DELETE /messaging/providers/{providerId} | 删除提供商 |
GET /messaging/providers/{providerId}/logs | 提供商发送日志 |
主题与订阅者(topics / subscribers)
| 方法 + 路径 | 用途 |
|---|---|
GET /messaging/topics | 列出主题 |
POST /messaging/topics | 创建主题 |
GET /messaging/topics/{topicId} | 获取主题 |
PATCH /messaging/topics/{topicId} | 更新主题 |
DELETE /messaging/topics/{topicId} | 删除主题 |
GET /messaging/topics/{topicId}/logs | 主题投递日志 |
GET /messaging/topics/{topicId}/subscribers | 列出订阅者 |
POST /messaging/topics/{topicId}/subscribers | 创建订阅 |
GET /messaging/topics/{topicId}/subscribers/{subscriberId} | 获取订阅 |
DELETE /messaging/topics/{topicId}/subscribers/{subscriberId} | 退订 |
GET /messaging/subscribers/{subscriberId}/logs | 订阅者投递日志 |
端点详解
立即发送、定时发送与草稿状态机:创建消息时若
draft=true,消息仅存为draft状态且不进入发送队列;若draft=false且未指定scheduledAt(或时间早于当前时刻),消息立即进入processing队列异步投递;若指定未来的scheduledAt(ISO 8601),消息处于scheduled状态并在到期前允许通过PATCH修改内容或收件人。
请求与响应
以下按端点逐个给出输入/输出规格、可复制的 curl 调用示例与响应示例。路径前缀 /v1;请求头 X-Appwrite-Project: <YOUR_PROJECT_ID> 与 X-Appwrite-Key: <YOUR_API_KEY> 对全部端点一致,示例中不再逐条解释。
消息
GET /v1/messaging/messages
分页列出项目内全部消息,可按状态、排期时间等过滤与关键词搜索(scope messages.read。SDK:Messages.listMessages。)
输入
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
queries | query | string[] | 否 | 默认 [] | 查询字符串数组,由 SDK 的 Query 构造器生成(形如 limit(25)、equal("name","x"));支持过滤、排序、分页(limit / cursorAfter / cursorBefore);可过滤属性:scheduledAt、deliveredAt、deliveredTotal、status、description、providerType。最多 100 条、每条最长 4096 字符。 |
search | query | string | 否 | — | 搜索词,模糊过滤列表结果。最长 256 字符。 |
total | query | boolean | 否 | 默认 true | 设为 false 时跳过总数计算,返回的 total 固定为 0。 |
输出:200,模型 messageList:total(匹配总数,total=false 时不计算)+ messages[](当前页数据)。
元素模型 message 关键字段:
| 字段 | 类型 | 说明 |
|---|---|---|
$id | string | 消息 ID。 |
$createdAt | string | 消息创建时间(ISO 8601)。 |
$updatedAt | string | 消息更新时间(ISO 8601)。 |
providerType | string | 消息通道类型(email / sms / push)。 |
topics | string[] | 作为收件人的主题 ID 列表。 |
users | string[] | 作为收件人的用户 ID 列表。 |
targets | string[] | 作为收件人的目标 ID 列表。 |
scheduledAt | string | 消息计划发送时间。 |
deliveredAt | string | 消息实际投递时间。 |
deliveryErrors | string[] | 投递错误列表(如有)。 |
deliveredTotal | integer | 已成功投递的收件人数。 |
data | object | 消息数据。 |
status | string | 投递状态。 |
调用示例:
curl -G "https://<your-endpoint>/v1/messaging/messages" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>" \
--data-urlencode "queries[]=limit(25)" \
--data-urlencode "search=welcome"响应示例:
{
"total": 5,
"messages": [
{
"$id": "66f1a2b3c4d5e6f7",
"$createdAt": "2020-10-15T06:38:00.000+00:00",
"$updatedAt": "2020-10-15T06:38:00.000+00:00",
"providerType": "email",
"topics": [
"announcements"
],
"users": [
"66b1c2d3e4f5a6b7"
],
"targets": [
"66c1d2e3f4a5b6c7"
],
"scheduledAt": null,
"deliveredAt": null,
"deliveryErrors": [],
"deliveredTotal": 0,
"data": {
"subject": "Welcome to AppBase",
"content": "Hi there, welcome to AppBase family."
},
"status": "draft"
}
]
}POST /v1/messaging/messages/email
创建一封邮件消息:draft=true 存草稿、scheduledAt 排期、否则进入投递流程(scope messages.write。SDK:Messages.createEmail。)
输入(application/json)
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
messageId | body | string | 是 | — | 消息 ID。可自定义,或用 SDK 的 ID.unique() 生成;仅允许 a-z、A-Z、0-9、句点、连字符、下划线,不能以特殊字符开头。最长 36 字符。 |
subject | body | string | 是 | — | 邮件主题。 |
content | body | string | 是 | — | 邮件正文。 |
topics | body | string[] | 否 | — | 主题 ID 列表。 |
users | body | string[] | 否 | — | 用户 ID 列表。 |
targets | body | string[] | 否 | — | 目标 ID 列表。 |
cc | body | string[] | 否 | — | 抄送(CC)目标 ID 数组。 |
bcc | body | string[] | 否 | — | 密送(BCC)目标 ID 数组。 |
attachments | body | string[] | 否 | — | 邮件附件的复合 ID 数组,格式为 <BUCKET_ID>:<FILE_ID>(文件须已在 Storage 上传)。 |
draft | body | boolean | 否 | — | 是否为草稿。 |
html | body | boolean | 否 | — | 正文是否为 HTML。 |
scheduledAt | body | string | 否 | 可为 null | 消息排期发送时间(ISO 8601)。必须是未来时间。 |
输出:201,模型 message,字段:
| 字段 | 类型 | 说明 |
|---|---|---|
$id | string | 消息 ID。 |
$createdAt | string | 消息创建时间(ISO 8601)。 |
$updatedAt | string | 消息更新时间(ISO 8601)。 |
providerType | string | 消息通道类型(email / sms / push)。 |
topics | string[] | 作为收件人的主题 ID 列表。 |
users | string[] | 作为收件人的用户 ID 列表。 |
targets | string[] | 作为收件人的目标 ID 列表。 |
scheduledAt | string | 消息计划发送时间。 |
deliveredAt | string | 消息实际投递时间。 |
deliveryErrors | string[] | 投递错误列表(如有)。 |
deliveredTotal | integer | 已成功投递的收件人数。 |
data | object | 消息数据。 |
status | string | 投递状态。 |
调用示例:
curl -X POST "https://<your-endpoint>/v1/messaging/messages/email" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>" \
-H "Content-Type: application/json" \
-d '{
"messageId": "welcome-email",
"subject": "欢迎使用 AppBase",
"content": "<h1>欢迎注册</h1>",
"topics": [
"announcements"
],
"html": true,
"cc": [
"66c1d2e3f4a5b6c7"
],
"bcc": [
"66d1e2f3a4b5c6d7"
],
"attachments": [
"attachments:66e1f2a3b4c5d6e7"
],
"draft": true
}'响应字段节选(省略与该操作无关的字段):
{
"$id": "welcome-email",
"$createdAt": "2020-10-15T06:38:00.000+00:00",
"$updatedAt": "2020-10-15T06:38:00.000+00:00",
"providerType": "email",
"topics": [
"announcements"
],
"users": [],
"targets": [],
"scheduledAt": null,
"deliveredAt": null,
"deliveryErrors": [],
"deliveredTotal": 0,
"data": {
"subject": "欢迎使用 AppBase",
"content": "<h1>欢迎注册</h1>"
},
"status": "draft"
}PATCH /v1/messaging/messages/email/{messageId}
更新邮件消息:仅 draft 状态可改;已进入 processing / sent / failed 的消息不可修改(scope messages.write。SDK:Messages.updateEmail。)
输入(application/json)
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
topics | body | string[] | 否 | 可为 null | 主题 ID 列表。 |
users | body | string[] | 否 | 可为 null | 用户 ID 列表。 |
targets | body | string[] | 否 | 可为 null | 目标 ID 列表。 |
subject | body | string | 否 | 可为 null | 邮件主题。 |
content | body | string | 否 | 可为 null | 邮件正文。 |
draft | body | boolean | 否 | 可为 null | 是否为草稿。 |
html | body | boolean | 否 | 可为 null | 正文是否为 HTML。 |
cc | body | string[] | 否 | 可为 null | 抄送(CC)目标 ID 数组。 |
bcc | body | string[] | 否 | 可为 null | 密送(BCC)目标 ID 数组。 |
scheduledAt | body | string | 否 | 可为 null | 消息排期发送时间(ISO 8601)。必须是未来时间。 |
attachments | body | string[] | 否 | 可为 null | 邮件附件的复合 ID 数组,格式为 <BUCKET_ID>:<FILE_ID>(文件须已在 Storage 上传)。 |
messageId | path | string | 是 | — | 消息 ID。 |
输出:200,模型 message(完整字段见前文),关键字段:
| 字段 | 类型 | 说明 |
|---|---|---|
$id | string | 消息 ID。 |
$createdAt | string | 消息创建时间(ISO 8601)。 |
$updatedAt | string | 消息更新时间(ISO 8601)。 |
providerType | string | 消息通道类型(email / sms / push)。 |
topics | string[] | 作为收件人的主题 ID 列表。 |
users | string[] | 作为收件人的用户 ID 列表。 |
targets | string[] | 作为收件人的目标 ID 列表。 |
scheduledAt | string | 消息计划发送时间。 |
deliveredAt | string | 消息实际投递时间。 |
deliveryErrors | string[] | 投递错误列表(如有)。 |
deliveredTotal | integer | 已成功投递的收件人数。 |
data | object | 消息数据。 |
status | string | 投递状态。 |
调用示例:
curl -X PATCH "https://<your-endpoint>/v1/messaging/messages/email/<MESSAGE_ID>" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>" \
-H "Content-Type: application/json" \
-d '{
"subject": "欢迎使用 AppBase",
"content": "<h1>欢迎注册</h1>",
"html": true
}'响应示例:
{
"$id": "66f1a2b3c4d5e6f7",
"$createdAt": "2020-10-15T06:38:00.000+00:00",
"$updatedAt": "2020-10-15T06:38:00.000+00:00",
"providerType": "email",
"topics": [
"announcements"
],
"users": [
"66b1c2d3e4f5a6b7"
],
"targets": [
"66c1d2e3f4a5b6c7"
],
"scheduledAt": null,
"deliveredAt": null,
"deliveryErrors": [],
"deliveredTotal": 0,
"data": {
"subject": "Welcome to AppBase",
"content": "Hi there, welcome to AppBase family."
},
"status": "draft"
}POST /v1/messaging/messages/sms
创建一条短信消息。该端点在 spec 中标记为 deprecated(v2.6.0 仍可用,SDK 保留对应方法)。(scope messages.write。SDK:Messages.createSms。)
输入(application/json)
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
messageId | body | string | 是 | — | 消息 ID。可自定义,或用 SDK 的 ID.unique() 生成;仅允许 a-z、A-Z、0-9、句点、连字符、下划线,不能以特殊字符开头。最长 36 字符。 |
content | body | string | 是 | — | 短信正文。 |
topics | body | string[] | 否 | — | 主题 ID 列表。 |
users | body | string[] | 否 | — | 用户 ID 列表。 |
targets | body | string[] | 否 | — | 目标 ID 列表。 |
draft | body | boolean | 否 | — | 是否为草稿。 |
scheduledAt | body | string | 否 | 可为 null | 消息排期发送时间(ISO 8601)。必须是未来时间。 |
输出:201,模型 message(完整字段见前文),关键字段:
| 字段 | 类型 | 说明 |
|---|---|---|
$id | string | 消息 ID。 |
$createdAt | string | 消息创建时间(ISO 8601)。 |
$updatedAt | string | 消息更新时间(ISO 8601)。 |
providerType | string | 消息通道类型(email / sms / push)。 |
topics | string[] | 作为收件人的主题 ID 列表。 |
users | string[] | 作为收件人的用户 ID 列表。 |
targets | string[] | 作为收件人的目标 ID 列表。 |
scheduledAt | string | 消息计划发送时间。 |
deliveredAt | string | 消息实际投递时间。 |
deliveryErrors | string[] | 投递错误列表(如有)。 |
deliveredTotal | integer | 已成功投递的收件人数。 |
data | object | 消息数据。 |
status | string | 投递状态。 |
调用示例:
curl -X POST "https://<your-endpoint>/v1/messaging/messages/sms" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>" \
-H "Content-Type: application/json" \
-d '{
"messageId": "notification-sms",
"content": "Welcome to Agentbase",
"topics": [
"announcements"
],
"users": [
"66b1c2d3e4f5a6b7"
],
"draft": true
}'响应字段节选(省略与该操作无关的字段):
{
"$id": "notification-sms",
"$createdAt": "2020-10-15T06:38:00.000+00:00",
"$updatedAt": "2020-10-15T06:38:00.000+00:00",
"providerType": "sms",
"topics": [
"announcements"
],
"users": [
"66b1c2d3e4f5a6b7"
],
"targets": [],
"scheduledAt": null,
"deliveredAt": null,
"deliveryErrors": [],
"deliveredTotal": 0,
"status": "draft"
}PATCH /v1/messaging/messages/sms/{messageId}
更新短信消息:仅 draft 状态可改。该端点在 spec 中标记为 deprecated(v2.6.0 仍可用,SDK 保留对应方法)。(scope messages.write。SDK:Messages.updateSms。)
输入(application/json)
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
topics | body | string[] | 否 | 可为 null | 主题 ID 列表。 |
users | body | string[] | 否 | 可为 null | 用户 ID 列表。 |
targets | body | string[] | 否 | 可为 null | 目标 ID 列表。 |
content | body | string | 否 | 可为 null | 邮件正文。 |
draft | body | boolean | 否 | 可为 null | 是否为草稿。 |
scheduledAt | body | string | 否 | 可为 null | 消息排期发送时间(ISO 8601)。必须是未来时间。 |
messageId | path | string | 是 | — | 消息 ID。 |
输出:200,模型 message(完整字段见前文),关键字段:
| 字段 | 类型 | 说明 |
|---|---|---|
$id | string | 消息 ID。 |
$createdAt | string | 消息创建时间(ISO 8601)。 |
$updatedAt | string | 消息更新时间(ISO 8601)。 |
providerType | string | 消息通道类型(email / sms / push)。 |
topics | string[] | 作为收件人的主题 ID 列表。 |
users | string[] | 作为收件人的用户 ID 列表。 |
targets | string[] | 作为收件人的目标 ID 列表。 |
scheduledAt | string | 消息计划发送时间。 |
deliveredAt | string | 消息实际投递时间。 |
deliveryErrors | string[] | 投递错误列表(如有)。 |
deliveredTotal | integer | 已成功投递的收件人数。 |
data | object | 消息数据。 |
status | string | 投递状态。 |
调用示例:
curl -X PATCH "https://<your-endpoint>/v1/messaging/messages/sms/<MESSAGE_ID>" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>" \
-H "Content-Type: application/json" \
-d '{
"content": "<h1>欢迎注册</h1>"
}'响应字段节选(省略与该操作无关的字段):
{
"$id": "66f1a2b3c4d5e6f7",
"$createdAt": "2020-10-15T06:38:00.000+00:00",
"$updatedAt": "2020-10-15T06:38:00.000+00:00",
"providerType": "sms",
"topics": [
"announcements"
],
"users": [
"66b1c2d3e4f5a6b7"
],
"targets": [
"66c1d2e3f4a5b6c7"
],
"scheduledAt": null,
"deliveredAt": null,
"deliveryErrors": [],
"deliveredTotal": 0,
"status": "draft"
}POST /v1/messaging/messages/push
创建一条推送通知:内容字段按 Android / iOS / Web 平台分别生效(scope messages.write。SDK:Messages.createPush。)
输入(application/json)
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
messageId | body | string | 是 | — | 消息 ID。可自定义,或用 SDK 的 ID.unique() 生成;仅允许 a-z、A-Z、0-9、句点、连字符、下划线,不能以特殊字符开头。最长 36 字符。 |
title | body | string | 否 | — | 推送标题。 |
body | body | string | 否 | — | 推送正文。 |
topics | body | string[] | 否 | — | 主题 ID 列表。 |
users | body | string[] | 否 | — | 用户 ID 列表。 |
targets | body | string[] | 否 | — | 目标 ID 列表。 |
data | body | object | 否 | 可为 null | 推送附加键值对数据。 |
action | body | string | 否 | — | 推送点击动作。 |
image | body | string | 否 | — | 推送大图。必须是 Storage 中 jpeg/png 图片的复合 ID,格式 <BUCKET_ID>:<FILE_ID>。 |
icon | body | string | 否 | — | 推送图标。仅 Android / Web 生效。 |
sound | body | string | 否 | — | 推送提示音。仅 Android / iOS 生效。 |
color | body | string | 否 | — | 推送颜色。仅 Android 生效。 |
tag | body | string | 否 | — | 推送标签(折叠同 tag 通知)。仅 Android 生效。 |
badge | body | integer | 否 | — | 应用角标数。仅 iOS 生效。 |
draft | body | boolean | 否 | — | 是否为草稿。 |
scheduledAt | body | string | 否 | 可为 null | 消息排期发送时间(ISO 8601)。必须是未来时间。 |
contentAvailable | body | boolean | 否 | — | 为 true 时静默后台投递。仅 iOS 生效。 |
critical | body | boolean | 否 | — | 为 true 时标记为重要通知,要求应用具备 critical notification entitlement。仅 iOS 生效。 |
priority | body | string | 否 | normal / high | 推送优先级。normal 会考虑设备状态、可能延迟投递;high 总是尝试立即投递。 |
imageInternal | body | boolean | 否 | — | 图片存放在内部默认桶时为 true。 |
输出:201,模型 message(完整字段见前文),关键字段:
| 字段 | 类型 | 说明 |
|---|---|---|
$id | string | 消息 ID。 |
$createdAt | string | 消息创建时间(ISO 8601)。 |
$updatedAt | string | 消息更新时间(ISO 8601)。 |
providerType | string | 消息通道类型(email / sms / push)。 |
topics | string[] | 作为收件人的主题 ID 列表。 |
users | string[] | 作为收件人的用户 ID 列表。 |
targets | string[] | 作为收件人的目标 ID 列表。 |
scheduledAt | string | 消息计划发送时间。 |
deliveredAt | string | 消息实际投递时间。 |
deliveryErrors | string[] | 投递错误列表(如有)。 |
deliveredTotal | integer | 已成功投递的收件人数。 |
data | object | 消息数据。 |
status | string | 投递状态。 |
调用示例:
curl -X POST "https://<your-endpoint>/v1/messaging/messages/push" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>" \
-H "Content-Type: application/json" \
-d '{
"messageId": "notification-push",
"topics": [
"announcements"
],
"data": {
"orderId": "1024"
},
"action": "open-orders",
"priority": "high",
"draft": true
}'响应字段节选(省略与该操作无关的字段):
{
"$id": "notification-push",
"$createdAt": "2020-10-15T06:38:00.000+00:00",
"$updatedAt": "2020-10-15T06:38:00.000+00:00",
"providerType": "push",
"topics": [
"announcements"
],
"users": [],
"targets": [],
"scheduledAt": null,
"deliveredAt": null,
"deliveryErrors": [],
"deliveredTotal": 0,
"status": "draft"
}PATCH /v1/messaging/messages/push/{messageId}
更新推送通知:仅 draft 状态可改(scope messages.write。SDK:Messages.updatePush。)
输入(application/json)
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
topics | body | string[] | 否 | 可为 null | 主题 ID 列表。 |
users | body | string[] | 否 | 可为 null | 用户 ID 列表。 |
targets | body | string[] | 否 | 可为 null | 目标 ID 列表。 |
title | body | string | 否 | 可为 null | 推送标题。 |
body | body | string | 否 | 可为 null | 推送正文。 |
data | body | object | 否 | 可为 null | 推送附加数据。 |
action | body | string | 否 | 可为 null | 推送点击动作。 |
image | body | string | 否 | 可为 null | 推送大图。必须是 Storage 中 jpeg/png 图片的复合 ID,格式 <BUCKET_ID>:<FILE_ID>。 |
icon | body | string | 否 | 可为 null | 推送图标。仅 Android / Web 生效。 |
sound | body | string | 否 | 可为 null | 推送提示音。仅 Android / iOS 生效。 |
color | body | string | 否 | 可为 null | 推送颜色。仅 Android 生效。 |
tag | body | string | 否 | 可为 null | 推送标签(折叠同 tag 通知)。仅 Android 生效。 |
badge | body | integer | 否 | 可为 null | 应用角标数。仅 iOS 生效。 |
draft | body | boolean | 否 | 可为 null | 是否为草稿。 |
scheduledAt | body | string | 否 | 可为 null | 消息排期发送时间(ISO 8601)。必须是未来时间。 |
contentAvailable | body | boolean | 否 | 可为 null | 为 true 时静默后台投递。仅 iOS 生效。 |
critical | body | boolean | 否 | 可为 null | 为 true 时标记为重要通知,要求应用具备 critical notification entitlement。仅 iOS 生效。 |
priority | body | string | 否 | normal / high;可为 null | 推送优先级。normal 会考虑设备电量状态、可能延迟发送;high 总是尝试立即投递。 |
imageInternal | body | boolean | 否 | — | 图片存放在内部默认桶时为 true。 |
messageId | path | string | 是 | — | 消息 ID。 |
输出:200,模型 message(完整字段见前文),关键字段:
| 字段 | 类型 | 说明 |
|---|---|---|
$id | string | 消息 ID。 |
$createdAt | string | 消息创建时间(ISO 8601)。 |
$updatedAt | string | 消息更新时间(ISO 8601)。 |
providerType | string | 消息通道类型(email / sms / push)。 |
topics | string[] | 作为收件人的主题 ID 列表。 |
users | string[] | 作为收件人的用户 ID 列表。 |
targets | string[] | 作为收件人的目标 ID 列表。 |
scheduledAt | string | 消息计划发送时间。 |
deliveredAt | string | 消息实际投递时间。 |
deliveryErrors | string[] | 投递错误列表(如有)。 |
deliveredTotal | integer | 已成功投递的收件人数。 |
data | object | 消息数据。 |
status | string | 投递状态。 |
调用示例:
curl -X PATCH "https://<your-endpoint>/v1/messaging/messages/push/<MESSAGE_ID>" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>" \
-H "Content-Type: application/json" \
-d '{
"title": "订单已发货",
"body": "{\"now\": true}"
}'响应字段节选(省略与该操作无关的字段):
{
"$id": "66f1a2b3c4d5e6f7",
"$createdAt": "2020-10-15T06:38:00.000+00:00",
"$updatedAt": "2020-10-15T06:38:00.000+00:00",
"providerType": "push",
"topics": [
"announcements"
],
"users": [
"66b1c2d3e4f5a6b7"
],
"targets": [
"66c1d2e3f4a5b6c7"
],
"scheduledAt": null,
"deliveredAt": null,
"deliveryErrors": [],
"deliveredTotal": 0,
"status": "draft"
}GET /v1/messaging/messages/{messageId}
读取单条消息及其投递状态(status、deliveredTotal、deliveryErrors)(scope messages.read。SDK:Messages.getMessage。)
输入
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
messageId | path | string | 是 | — | 消息 ID。 |
输出:200,模型 message(完整字段见前文),关键字段:
| 字段 | 类型 | 说明 |
|---|---|---|
$id | string | 消息 ID。 |
$createdAt | string | 消息创建时间(ISO 8601)。 |
$updatedAt | string | 消息更新时间(ISO 8601)。 |
providerType | string | 消息通道类型(email / sms / push)。 |
topics | string[] | 作为收件人的主题 ID 列表。 |
users | string[] | 作为收件人的用户 ID 列表。 |
targets | string[] | 作为收件人的目标 ID 列表。 |
scheduledAt | string | 消息计划发送时间。 |
deliveredAt | string | 消息实际投递时间。 |
deliveryErrors | string[] | 投递错误列表(如有)。 |
deliveredTotal | integer | 已成功投递的收件人数。 |
data | object | 消息数据。 |
status | string | 投递状态。 |
调用示例:
curl "https://<your-endpoint>/v1/messaging/messages/<MESSAGE_ID>" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>"响应示例:
{
"$id": "66f1a2b3c4d5e6f7",
"$createdAt": "2020-10-15T06:38:00.000+00:00",
"$updatedAt": "2020-10-15T06:38:00.000+00:00",
"providerType": "email",
"topics": [
"announcements"
],
"users": [
"66b1c2d3e4f5a6b7"
],
"targets": [
"66c1d2e3f4a5b6c7"
],
"scheduledAt": null,
"deliveredAt": null,
"deliveryErrors": [],
"deliveredTotal": 0,
"data": {
"subject": "Welcome to AppBase",
"content": "Hi there, welcome to AppBase family."
},
"status": "draft"
}DELETE /v1/messaging/messages/{messageId}
删除消息:已发送的消息不会被撤回,仅删除记录;草稿/排期消息取消投递(scope messages.write。SDK:Messages.delete。)
输入
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
messageId | path | string | 是 | — | 消息 ID。 |
输出:204 无响应体。
调用示例:
curl -X DELETE "https://<your-endpoint>/v1/messaging/messages/<MESSAGE_ID>" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>"响应示例:
_二进制流或无响应体(见输出说明)。_
GET /v1/messaging/messages/{messageId}/targets
列出消息中通过 targets 显式指定的收件目标;不展开 topics 或 users,未指定 targets 时返回空列表(scope messages.read。SDK:Messages.listTargets。)
输入
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
messageId | path | string | 是 | — | 消息 ID。 |
queries | query | string[] | 否 | 默认 [] | 查询字符串数组,由 SDK 的 Query 构造器生成(形如 limit(25)、equal("name","x"));支持过滤、排序、分页(limit / cursorAfter / cursorBefore);可过滤属性:userId、providerId、identifier、providerType。最多 100 条、每条最长 4096 字符。 |
total | query | boolean | 否 | 默认 true | 设为 false 时跳过总数计算,返回的 total 固定为 0。 |
输出:200,模型 targetList:total(匹配总数,total=false 时不计算)+ targets[](当前页数据)。
元素模型 target 关键字段:
| 字段 | 类型 | 说明 |
|---|---|---|
$id | string | 目标 ID。 |
$createdAt | string | 目标创建时间(ISO 8601)。 |
$updatedAt | string | 目标更新时间(ISO 8601)。 |
name | string | 目标名称。 |
userId | string | 用户 ID。 |
providerType | string | 目标通道类型:email / sms / push。 |
identifier | string | 目标标识(邮箱地址 / 手机号 / 推送令牌)。 |
expired | boolean | 目标是否已过期。 |
调用示例:
curl -G "https://<your-endpoint>/v1/messaging/messages/<MESSAGE_ID>/targets" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>" \
--data-urlencode "queries[]=limit(25)"响应示例:
{
"total": 1,
"targets": [
{
"$id": "66f1a2b3c4d5e6f7",
"$createdAt": "2020-10-15T06:38:00.000+00:00",
"$updatedAt": "2020-10-15T06:38:00.000+00:00",
"name": "Apple iPhone 12",
"userId": "259125845563242502",
"providerId": "259125845563242502",
"providerType": "push",
"identifier": "token",
"expired": false
}
]
}GET /v1/messaging/messages/{messageId}/logs
列出该消息的投递日志(仅支持 limit/offset 分页)(scope messages.read。SDK:Logs.listMessageLogs。)
输入
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
messageId | path | string | 是 | — | 消息 ID。 |
queries | query | string[] | 否 | 默认 [] | 查询字符串数组,由 SDK 的 Query 构造器生成(形如 limit(25)、equal("name","x"));仅支持 limit / offset 两个方法。 |
total | query | boolean | 否 | 默认 true | 设为 false 时跳过总数计算,返回的 total 固定为 0。 |
输出:200,模型 logList:total(匹配总数,total=false 时不计算)+ logs[](当前页数据)。
元素模型 log 关键字段:
| 字段 | 类型 | 说明 |
|---|---|---|
event | string | 事件名。 |
userId | string | 触发该日志的用户 ID。被代理(impersonation)时记录代理发起者而非被代理用户。 |
userEmail | string | 触发该日志的用户邮箱。 |
mode | string | 事件触发时的 API 模式(admin/key 等)。 |
ip | string | 事件发生时的来源 IP。 |
time | string | 日志创建时间(ISO 8601)。 |
clientName | string | 客户端名称。 |
countryName | string | 国家/地区名称。 |
调用示例:
curl -G "https://<your-endpoint>/v1/messaging/messages/<MESSAGE_ID>/logs" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>" \
--data-urlencode "queries[]=limit(25)"响应示例:
{
"total": 5,
"logs": ""
}提供商
GET /v1/messaging/providers
分页列出项目内全部消息提供商(scope providers.read。SDK:Providers.listProviders。)
输入
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
queries | query | string[] | 否 | 默认 [] | 查询字符串数组,由 SDK 的 Query 构造器生成(形如 limit(25)、equal("name","x"));支持过滤、排序、分页(limit / cursorAfter / cursorBefore);可过滤属性:name、provider、type、enabled。最多 100 条、每条最长 4096 字符。 |
search | query | string | 否 | — | 搜索词,模糊过滤列表结果。最长 256 字符。 |
total | query | boolean | 否 | 默认 true | 设为 false 时跳过总数计算,返回的 total 固定为 0。 |
输出:200,模型 providerList:total(匹配总数,total=false 时不计算)+ providers[](当前页数据)。
元素模型 provider 关键字段:
| 字段 | 类型 | 说明 |
|---|---|---|
$id | string | 提供商 ID。 |
$createdAt | string | 提供商创建时间(ISO 8601)。 |
$updatedAt | string | 提供商更新时间(ISO 8601)。 |
name | string | 提供商实例名称。 |
provider | string | 提供商服务标识。 |
enabled | boolean | 提供商是否启用。 |
type | string | 提供商通道类型。 |
credentials | object | 提供商凭证;字段和响应内容因提供商及部署配置而异。 |
options | object | 提供商选项。 |
调用示例:
curl -G "https://<your-endpoint>/v1/messaging/providers" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>" \
--data-urlencode "queries[]=limit(25)" \
--data-urlencode "search=welcome"响应字段节选:
{
"total": 5,
"providers": [
{
"$id": "66f1a2b3c4d5e6f7",
"$createdAt": "2020-10-15T06:38:00.000+00:00",
"$updatedAt": "2020-10-15T06:38:00.000+00:00",
"name": "Mailgun",
"provider": "mailgun",
"enabled": true,
"type": "email"
}
]
}POST /v1/messaging/providers/apns
创建 Apple Push Notification service(APNS)提供商:使用 .p8 密钥三件套(authKey/authKeyId/teamId)。该端点在 spec 中标记为 deprecated(v2.6.0 仍可用,SDK 保留对应方法)。(scope providers.write。SDK:Providers.createApnsProvider。)
输入(application/json)
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
providerId | body | string | 是 | — | 提供商 ID。可自定义,或用 SDK 的 ID.unique() 生成;仅允许 a-z、A-Z、0-9、句点、连字符、下划线,不能以特殊字符开头。最长 36 字符。 |
name | body | string | 是 | — | 提供商名称。 |
authKey | body | string | 否 | — | APNS 认证密钥(.p8 私钥内容)。 |
authKeyId | body | string | 否 | — | APNS 密钥 ID。 |
teamId | body | string | 否 | — | APNS 团队 ID。 |
bundleId | body | string | 否 | — | 应用 Bundle ID。 |
sandbox | body | boolean | 否 | — | 是否使用 APNS 沙箱环境。 |
enabled | body | boolean | 否 | 可为 null | 是否启用。 |
输出:201,模型 provider,字段:
| 字段 | 类型 | 说明 |
|---|---|---|
$id | string | 提供商 ID。 |
$createdAt | string | 提供商创建时间(ISO 8601)。 |
$updatedAt | string | 提供商更新时间(ISO 8601)。 |
name | string | 提供商实例名称。 |
provider | string | 提供商服务标识。 |
enabled | boolean | 提供商是否启用。 |
type | string | 提供商通道类型。 |
credentials | object | 提供商凭证;字段和响应内容因提供商及部署配置而异。 |
options | object | 提供商选项。 |
调用示例:
curl -X POST "https://<your-endpoint>/v1/messaging/providers/apns" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>" \
-H "Content-Type: application/json" \
-d '{
"providerId": "apns-main",
"name": "APNS",
"authKey": "-----BEGIN PRIVATE KEY-----\\nMIGT...\\n-----END PRIVATE KEY-----",
"authKeyId": "ABC123DEFG",
"teamId": "TEAMID12345",
"bundleId": "com.example.app",
"sandbox": false,
"enabled": true
}'响应字段节选(省略与该操作无关的字段):
{
"$id": "apns-main",
"$createdAt": "2020-10-15T06:38:00.000+00:00",
"$updatedAt": "2020-10-15T06:38:00.000+00:00",
"name": "APNS",
"provider": "apns",
"enabled": true,
"type": "push"
}PATCH /v1/messaging/providers/apns/{providerId}
更新 APNS 提供商:未提供的字段保留现值。该端点在 spec 中标记为 deprecated(v2.6.0 仍可用,SDK 保留对应方法)。(scope providers.write。SDK:Providers.updateApnsProvider。)
输入(application/json)
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
name | body | string | 否 | — | 提供商名称。 |
enabled | body | boolean | 否 | 可为 null | 是否启用。 |
authKey | body | string | 否 | — | APNS 认证密钥(.p8 私钥内容)。 |
authKeyId | body | string | 否 | — | APNS 密钥 ID。 |
teamId | body | string | 否 | — | APNS 团队 ID。 |
bundleId | body | string | 否 | — | 应用 Bundle ID。 |
sandbox | body | boolean | 否 | 可为 null | 是否使用 APNS 沙箱环境。 |
providerId | path | string | 是 | — | 提供商 ID。 |
输出:200,模型 provider(完整字段见前文),关键字段:
| 字段 | 类型 | 说明 |
|---|---|---|
$id | string | 提供商 ID。 |
$createdAt | string | 提供商创建时间(ISO 8601)。 |
$updatedAt | string | 提供商更新时间(ISO 8601)。 |
name | string | 提供商实例名称。 |
provider | string | 提供商服务标识。 |
enabled | boolean | 提供商是否启用。 |
type | string | 提供商通道类型。 |
credentials | object | 提供商凭证;字段和响应内容因提供商及部署配置而异。 |
options | object | 提供商选项。 |
调用示例:
curl -X PATCH "https://<your-endpoint>/v1/messaging/providers/apns/<PROVIDER_ID>" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>" \
-H "Content-Type: application/json" \
-d '{
"name": "APNS",
"enabled": true,
"authKey": "-----BEGIN PRIVATE KEY-----\\nMIGT...\\n-----END PRIVATE KEY-----",
"authKeyId": "ABC123DEFG",
"teamId": "TEAMID12345",
"bundleId": "com.example.app",
"sandbox": false
}'响应字段节选(省略与该操作无关的字段):
{
"$id": "66f1a2b3c4d5e6f7",
"$createdAt": "2020-10-15T06:38:00.000+00:00",
"$updatedAt": "2020-10-15T06:38:00.000+00:00",
"name": "APNS",
"provider": "apns",
"enabled": true,
"type": "push"
}POST /v1/messaging/providers/fcm
创建 Firebase Cloud Messaging(FCM)提供商:提交服务账号 JSON。该端点在 spec 中标记为 deprecated(v2.6.0 仍可用,SDK 保留对应方法)。(scope providers.write。SDK:Providers.createFcmProvider。)
输入(application/json)
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
providerId | body | string | 是 | — | 提供商 ID。可自定义,或用 SDK 的 ID.unique() 生成;仅允许 a-z、A-Z、0-9、句点、连字符、下划线,不能以特殊字符开头。最长 36 字符。 |
name | body | string | 是 | — | 提供商名称。 |
serviceAccountJSON | body | object | 否 | 可为 null | FCM 服务账号 JSON。 |
enabled | body | boolean | 否 | 可为 null | 是否启用。 |
输出:201,模型 provider(完整字段见前文),关键字段:
| 字段 | 类型 | 说明 |
|---|---|---|
$id | string | 提供商 ID。 |
$createdAt | string | 提供商创建时间(ISO 8601)。 |
$updatedAt | string | 提供商更新时间(ISO 8601)。 |
name | string | 提供商实例名称。 |
provider | string | 提供商服务标识。 |
enabled | boolean | 提供商是否启用。 |
type | string | 提供商通道类型。 |
credentials | object | 提供商凭证;字段和响应内容因提供商及部署配置而异。 |
options | object | 提供商选项。 |
调用示例:
curl -X POST "https://<your-endpoint>/v1/messaging/providers/fcm" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>" \
-H "Content-Type: application/json" \
-d '{
"providerId": "fcm-main",
"name": "FCM",
"serviceAccountJSON": {
"type": "service_account",
"project_id": "my-project"
},
"enabled": true
}'响应字段节选(省略与该操作无关的字段):
{
"$id": "fcm-main",
"$createdAt": "2020-10-15T06:38:00.000+00:00",
"$updatedAt": "2020-10-15T06:38:00.000+00:00",
"name": "FCM",
"provider": "fcm",
"enabled": true,
"type": "push"
}PATCH /v1/messaging/providers/fcm/{providerId}
更新 FCM 提供商。该端点在 spec 中标记为 deprecated(v2.6.0 仍可用,SDK 保留对应方法)。(scope providers.write。SDK:Providers.updateFcmProvider。)
输入(application/json)
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
name | body | string | 否 | — | 提供商名称。 |
enabled | body | boolean | 否 | 可为 null | 是否启用。 |
serviceAccountJSON | body | object | 否 | 可为 null | FCM 服务账号 JSON。 |
providerId | path | string | 是 | — | 提供商 ID。 |
输出:200,模型 provider(完整字段见前文),关键字段:
| 字段 | 类型 | 说明 |
|---|---|---|
$id | string | 提供商 ID。 |
$createdAt | string | 提供商创建时间(ISO 8601)。 |
$updatedAt | string | 提供商更新时间(ISO 8601)。 |
name | string | 提供商实例名称。 |
provider | string | 提供商服务标识。 |
enabled | boolean | 提供商是否启用。 |
type | string | 提供商通道类型。 |
credentials | object | 提供商凭证;字段和响应内容因提供商及部署配置而异。 |
options | object | 提供商选项。 |
调用示例:
curl -X PATCH "https://<your-endpoint>/v1/messaging/providers/fcm/<PROVIDER_ID>" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>" \
-H "Content-Type: application/json" \
-d '{
"name": "FCM",
"enabled": true,
"serviceAccountJSON": {
"type": "service_account",
"project_id": "my-project"
}
}'响应字段节选(省略与该操作无关的字段):
{
"$id": "66f1a2b3c4d5e6f7",
"$createdAt": "2020-10-15T06:38:00.000+00:00",
"$updatedAt": "2020-10-15T06:38:00.000+00:00",
"name": "FCM",
"provider": "fcm",
"enabled": true,
"type": "push"
}POST /v1/messaging/providers/mailgun
创建 Mailgun 邮件提供商(scope providers.write。SDK:Providers.createMailgunProvider。)
输入(application/json)
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
providerId | body | string | 是 | — | 提供商 ID。可自定义,或用 SDK 的 ID.unique() 生成;仅允许 a-z、A-Z、0-9、句点、连字符、下划线,不能以特殊字符开头。最长 36 字符。 |
name | body | string | 是 | — | 提供商名称。 |
apiKey | body | string | 否 | — | Mailgun API Key。 |
domain | body | string | 否 | — | Mailgun 域名。 |
isEuRegion | body | boolean | 否 | 可为 null | 是否使用 Mailgun 欧盟区域。 |
fromName | body | string | 否 | — | 发件人名称。 |
fromEmail | body | string | 否 | — | 发件人邮箱。 |
replyToName | body | string | 否 | — | 邮件 Reply-To 名称。默认取发件人名称;须与 Reply-To 邮箱同时提供。 |
replyToEmail | body | string | 否 | — | 邮件 Reply-To 邮箱。默认取发件人邮箱;须与 Reply-To 名称同时提供。 |
enabled | body | boolean | 否 | 可为 null | 是否启用。 |
输出:201,模型 provider(完整字段见前文),关键字段:
| 字段 | 类型 | 说明 |
|---|---|---|
$id | string | 提供商 ID。 |
$createdAt | string | 提供商创建时间(ISO 8601)。 |
$updatedAt | string | 提供商更新时间(ISO 8601)。 |
name | string | 提供商实例名称。 |
provider | string | 提供商服务标识。 |
enabled | boolean | 提供商是否启用。 |
type | string | 提供商通道类型。 |
credentials | object | 提供商凭证;字段和响应内容因提供商及部署配置而异。 |
options | object | 提供商选项。 |
调用示例:
curl -X POST "https://<your-endpoint>/v1/messaging/providers/mailgun" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>" \
-H "Content-Type: application/json" \
-d '{
"providerId": "mailgun-main",
"name": "MAILGUN",
"apiKey": "key-1234567890abcdef",
"domain": "mg.example.com",
"isEuRegion": false,
"fromName": "AppBase",
"fromEmail": "noreply@example.com",
"replyToName": "支持团队",
"replyToEmail": "support@example.com",
"enabled": true
}'响应字段节选(省略与该操作无关的字段):
{
"$id": "mailgun-main",
"$createdAt": "2020-10-15T06:38:00.000+00:00",
"$updatedAt": "2020-10-15T06:38:00.000+00:00",
"name": "MAILGUN",
"provider": "mailgun",
"enabled": true,
"type": "email"
}PATCH /v1/messaging/providers/mailgun/{providerId}
更新 Mailgun 提供商(scope providers.write。SDK:Providers.updateMailgunProvider。)
输入(application/json)
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
name | body | string | 否 | — | 提供商名称。 |
apiKey | body | string | 否 | — | Mailgun API Key。 |
domain | body | string | 否 | — | Mailgun 域名。 |
isEuRegion | body | boolean | 否 | 可为 null | 是否使用 Mailgun 欧盟区域。 |
enabled | body | boolean | 否 | 可为 null | 是否启用。 |
fromName | body | string | 否 | — | 发件人名称。 |
fromEmail | body | string | 否 | — | 发件人邮箱。 |
replyToName | body | string | 否 | — | 邮件 Reply-To 名称。默认取发件人名称。 |
replyToEmail | body | string | 否 | — | 邮件 Reply-To 邮箱。默认取发件人邮箱。 |
providerId | path | string | 是 | — | 提供商 ID。 |
输出:200,模型 provider(完整字段见前文),关键字段:
| 字段 | 类型 | 说明 |
|---|---|---|
$id | string | 提供商 ID。 |
$createdAt | string | 提供商创建时间(ISO 8601)。 |
$updatedAt | string | 提供商更新时间(ISO 8601)。 |
name | string | 提供商实例名称。 |
provider | string | 提供商服务标识。 |
enabled | boolean | 提供商是否启用。 |
type | string | 提供商通道类型。 |
credentials | object | 提供商凭证;字段和响应内容因提供商及部署配置而异。 |
options | object | 提供商选项。 |
调用示例:
curl -X PATCH "https://<your-endpoint>/v1/messaging/providers/mailgun/<PROVIDER_ID>" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>" \
-H "Content-Type: application/json" \
-d '{
"name": "MAILGUN",
"apiKey": "key-1234567890abcdef",
"domain": "mg.example.com",
"isEuRegion": false,
"enabled": true,
"fromName": "AppBase",
"fromEmail": "noreply@example.com",
"replyToName": "支持团队",
"replyToEmail": "support@example.com"
}'响应字段节选(省略与该操作无关的字段):
{
"$id": "66f1a2b3c4d5e6f7",
"$createdAt": "2020-10-15T06:38:00.000+00:00",
"$updatedAt": "2020-10-15T06:38:00.000+00:00",
"name": "MAILGUN",
"provider": "mailgun",
"enabled": true,
"type": "email"
}POST /v1/messaging/providers/msg91
创建 MSG91 短信提供商(scope providers.write。SDK:Providers.createMsg91Provider。)
输入(application/json)
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
providerId | body | string | 是 | — | 提供商 ID。可自定义,或用 SDK 的 ID.unique() 生成;仅允许 a-z、A-Z、0-9、句点、连字符、下划线,不能以特殊字符开头。最长 36 字符。 |
name | body | string | 是 | — | 提供商名称。 |
templateId | body | string | 否 | — | MSG91 模板 ID。 |
senderId | body | string | 否 | — | MSG91 发件人 ID。 |
authKey | body | string | 否 | — | MSG91 认证密钥。 |
enabled | body | boolean | 否 | 可为 null | 是否启用。 |
输出:201,模型 provider(完整字段见前文),关键字段:
| 字段 | 类型 | 说明 |
|---|---|---|
$id | string | 提供商 ID。 |
$createdAt | string | 提供商创建时间(ISO 8601)。 |
$updatedAt | string | 提供商更新时间(ISO 8601)。 |
name | string | 提供商实例名称。 |
provider | string | 提供商服务标识。 |
enabled | boolean | 提供商是否启用。 |
type | string | 提供商通道类型。 |
credentials | object | 提供商凭证;字段和响应内容因提供商及部署配置而异。 |
options | object | 提供商选项。 |
调用示例:
curl -X POST "https://<your-endpoint>/v1/messaging/providers/msg91" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>" \
-H "Content-Type: application/json" \
-d '{
"providerId": "msg91-main",
"name": "MSG91",
"templateId": "6789abcdef012345",
"senderId": "APPBASE",
"authKey": "-----BEGIN PRIVATE KEY-----\\nMIGT...\\n-----END PRIVATE KEY-----",
"enabled": true
}'响应字段节选(省略与该操作无关的字段):
{
"$id": "msg91-main",
"$createdAt": "2020-10-15T06:38:00.000+00:00",
"$updatedAt": "2020-10-15T06:38:00.000+00:00",
"name": "MSG91",
"provider": "msg91",
"enabled": true,
"type": "sms"
}PATCH /v1/messaging/providers/msg91/{providerId}
更新 MSG91 提供商(scope providers.write。SDK:Providers.updateMsg91Provider。)
输入(application/json)
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
name | body | string | 否 | — | 提供商名称。 |
enabled | body | boolean | 否 | 可为 null | 是否启用。 |
templateId | body | string | 否 | — | MSG91 模板 ID。 |
senderId | body | string | 否 | — | MSG91 发件人 ID。 |
authKey | body | string | 否 | — | MSG91 认证密钥。 |
providerId | path | string | 是 | — | 提供商 ID。 |
输出:200,模型 provider(完整字段见前文),关键字段:
| 字段 | 类型 | 说明 |
|---|---|---|
$id | string | 提供商 ID。 |
$createdAt | string | 提供商创建时间(ISO 8601)。 |
$updatedAt | string | 提供商更新时间(ISO 8601)。 |
name | string | 提供商实例名称。 |
provider | string | 提供商服务标识。 |
enabled | boolean | 提供商是否启用。 |
type | string | 提供商通道类型。 |
credentials | object | 提供商凭证;字段和响应内容因提供商及部署配置而异。 |
options | object | 提供商选项。 |
调用示例:
curl -X PATCH "https://<your-endpoint>/v1/messaging/providers/msg91/<PROVIDER_ID>" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>" \
-H "Content-Type: application/json" \
-d '{
"name": "MSG91",
"enabled": true,
"templateId": "6789abcdef012345",
"senderId": "APPBASE",
"authKey": "-----BEGIN PRIVATE KEY-----\\nMIGT...\\n-----END PRIVATE KEY-----"
}'响应字段节选(省略与该操作无关的字段):
{
"$id": "66f1a2b3c4d5e6f7",
"$createdAt": "2020-10-15T06:38:00.000+00:00",
"$updatedAt": "2020-10-15T06:38:00.000+00:00",
"name": "MSG91",
"provider": "msg91",
"enabled": true,
"type": "sms"
}POST /v1/messaging/providers/resend
创建 Resend 邮件提供商(scope providers.write。SDK:Providers.createResendProvider。)
输入(application/json)
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
providerId | body | string | 是 | — | 提供商 ID。可自定义,或用 SDK 的 ID.unique() 生成;仅允许 a-z、A-Z、0-9、句点、连字符、下划线,不能以特殊字符开头。最长 36 字符。 |
name | body | string | 是 | — | 提供商名称。 |
apiKey | body | string | 否 | — | Resend API Key。 |
fromName | body | string | 否 | — | 发件人名称。 |
fromEmail | body | string | 否 | — | 发件人邮箱。 |
replyToName | body | string | 否 | — | 邮件 Reply-To 名称。默认取发件人名称。 |
replyToEmail | body | string | 否 | — | 邮件 Reply-To 邮箱。默认取发件人邮箱。 |
enabled | body | boolean | 否 | 可为 null | 是否启用。 |
输出:201,模型 provider(完整字段见前文),关键字段:
| 字段 | 类型 | 说明 |
|---|---|---|
$id | string | 提供商 ID。 |
$createdAt | string | 提供商创建时间(ISO 8601)。 |
$updatedAt | string | 提供商更新时间(ISO 8601)。 |
name | string | 提供商实例名称。 |
provider | string | 提供商服务标识。 |
enabled | boolean | 提供商是否启用。 |
type | string | 提供商通道类型。 |
credentials | object | 提供商凭证;字段和响应内容因提供商及部署配置而异。 |
options | object | 提供商选项。 |
调用示例:
curl -X POST "https://<your-endpoint>/v1/messaging/providers/resend" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>" \
-H "Content-Type: application/json" \
-d '{
"providerId": "resend-main",
"name": "RESEND",
"apiKey": "key-1234567890abcdef",
"fromName": "AppBase",
"fromEmail": "noreply@example.com",
"replyToName": "支持团队",
"replyToEmail": "support@example.com",
"enabled": true
}'响应字段节选(省略与该操作无关的字段):
{
"$id": "resend-main",
"$createdAt": "2020-10-15T06:38:00.000+00:00",
"$updatedAt": "2020-10-15T06:38:00.000+00:00",
"name": "RESEND",
"provider": "resend",
"enabled": true,
"type": "email"
}PATCH /v1/messaging/providers/resend/{providerId}
更新 Resend 提供商(scope providers.write。SDK:Providers.updateResendProvider。)
输入(application/json)
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
name | body | string | 否 | — | 提供商名称。 |
enabled | body | boolean | 否 | 可为 null | 是否启用。 |
apiKey | body | string | 否 | — | Resend API Key。 |
fromName | body | string | 否 | — | 发件人名称。 |
fromEmail | body | string | 否 | — | 发件人邮箱。 |
replyToName | body | string | 否 | — | 邮件 Reply-To 名称。默认取发件人名称。 |
replyToEmail | body | string | 否 | — | 邮件 Reply-To 邮箱。默认取发件人邮箱。 |
providerId | path | string | 是 | — | 提供商 ID。 |
输出:200,模型 provider(完整字段见前文),关键字段:
| 字段 | 类型 | 说明 |
|---|---|---|
$id | string | 提供商 ID。 |
$createdAt | string | 提供商创建时间(ISO 8601)。 |
$updatedAt | string | 提供商更新时间(ISO 8601)。 |
name | string | 提供商实例名称。 |
provider | string | 提供商服务标识。 |
enabled | boolean | 提供商是否启用。 |
type | string | 提供商通道类型。 |
credentials | object | 提供商凭证;字段和响应内容因提供商及部署配置而异。 |
options | object | 提供商选项。 |
调用示例:
curl -X PATCH "https://<your-endpoint>/v1/messaging/providers/resend/<PROVIDER_ID>" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>" \
-H "Content-Type: application/json" \
-d '{
"name": "RESEND",
"enabled": true,
"apiKey": "key-1234567890abcdef",
"fromName": "AppBase",
"fromEmail": "noreply@example.com",
"replyToName": "支持团队",
"replyToEmail": "support@example.com"
}'响应字段节选(省略与该操作无关的字段):
{
"$id": "66f1a2b3c4d5e6f7",
"$createdAt": "2020-10-15T06:38:00.000+00:00",
"$updatedAt": "2020-10-15T06:38:00.000+00:00",
"name": "RESEND",
"provider": "resend",
"enabled": true,
"type": "email"
}POST /v1/messaging/providers/sendgrid
创建 SendGrid 邮件提供商(scope providers.write。SDK:Providers.createSendgridProvider。)
输入(application/json)
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
providerId | body | string | 是 | — | 提供商 ID。可自定义,或用 SDK 的 ID.unique() 生成;仅允许 a-z、A-Z、0-9、句点、连字符、下划线,不能以特殊字符开头。最长 36 字符。 |
name | body | string | 是 | — | 提供商名称。 |
apiKey | body | string | 否 | — | SendGrid API Key。 |
fromName | body | string | 否 | — | 发件人名称。 |
fromEmail | body | string | 否 | — | 发件人邮箱。 |
replyToName | body | string | 否 | — | 邮件 Reply-To 名称。默认取发件人名称。 |
replyToEmail | body | string | 否 | — | 邮件 Reply-To 邮箱。默认取发件人邮箱。 |
enabled | body | boolean | 否 | 可为 null | 是否启用。 |
输出:201,模型 provider(完整字段见前文),关键字段:
| 字段 | 类型 | 说明 |
|---|---|---|
$id | string | 提供商 ID。 |
$createdAt | string | 提供商创建时间(ISO 8601)。 |
$updatedAt | string | 提供商更新时间(ISO 8601)。 |
name | string | 提供商实例名称。 |
provider | string | 提供商服务标识。 |
enabled | boolean | 提供商是否启用。 |
type | string | 提供商通道类型。 |
credentials | object | 提供商凭证;字段和响应内容因提供商及部署配置而异。 |
options | object | 提供商选项。 |
调用示例:
curl -X POST "https://<your-endpoint>/v1/messaging/providers/sendgrid" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>" \
-H "Content-Type: application/json" \
-d '{
"providerId": "sendgrid-main",
"name": "SENDGRID",
"apiKey": "key-1234567890abcdef",
"fromName": "AppBase",
"fromEmail": "noreply@example.com",
"replyToName": "支持团队",
"replyToEmail": "support@example.com",
"enabled": true
}'响应字段节选(省略与该操作无关的字段):
{
"$id": "sendgrid-main",
"$createdAt": "2020-10-15T06:38:00.000+00:00",
"$updatedAt": "2020-10-15T06:38:00.000+00:00",
"name": "SENDGRID",
"provider": "sendgrid",
"enabled": true,
"type": "email"
}PATCH /v1/messaging/providers/sendgrid/{providerId}
更新 SendGrid 提供商(scope providers.write。SDK:Providers.updateSendgridProvider。)
输入(application/json)
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
name | body | string | 否 | — | 提供商名称。 |
enabled | body | boolean | 否 | 可为 null | 是否启用。 |
apiKey | body | string | 否 | — | SendGrid API Key。 |
fromName | body | string | 否 | — | 发件人名称。 |
fromEmail | body | string | 否 | — | 发件人邮箱。 |
replyToName | body | string | 否 | — | 邮件 Reply-To 名称。默认取发件人名称。 |
replyToEmail | body | string | 否 | — | 邮件 Reply-To 邮箱。默认取发件人邮箱。 |
providerId | path | string | 是 | — | 提供商 ID。 |
输出:200,模型 provider(完整字段见前文),关键字段:
| 字段 | 类型 | 说明 |
|---|---|---|
$id | string | 提供商 ID。 |
$createdAt | string | 提供商创建时间(ISO 8601)。 |
$updatedAt | string | 提供商更新时间(ISO 8601)。 |
name | string | 提供商实例名称。 |
provider | string | 提供商服务标识。 |
enabled | boolean | 提供商是否启用。 |
type | string | 提供商通道类型。 |
credentials | object | 提供商凭证;字段和响应内容因提供商及部署配置而异。 |
options | object | 提供商选项。 |
调用示例:
curl -X PATCH "https://<your-endpoint>/v1/messaging/providers/sendgrid/<PROVIDER_ID>" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>" \
-H "Content-Type: application/json" \
-d '{
"name": "SENDGRID",
"enabled": true,
"apiKey": "key-1234567890abcdef",
"fromName": "AppBase",
"fromEmail": "noreply@example.com",
"replyToName": "支持团队",
"replyToEmail": "support@example.com"
}'响应字段节选(省略与该操作无关的字段):
{
"$id": "66f1a2b3c4d5e6f7",
"$createdAt": "2020-10-15T06:38:00.000+00:00",
"$updatedAt": "2020-10-15T06:38:00.000+00:00",
"name": "SENDGRID",
"provider": "sendgrid",
"enabled": true,
"type": "email"
}POST /v1/messaging/providers/smtp
创建通用 SMTP 邮件提供商:主机、端口、加密方式与认证凭证。该端点在 spec 中标记为 deprecated(v2.6.0 仍可用,SDK 保留对应方法)。(scope providers.write。SDK:Providers.createSmtpProvider。)
输入(application/json)
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
providerId | body | string | 是 | — | 提供商 ID。可自定义,或用 SDK 的 ID.unique() 生成;仅允许 a-z、A-Z、0-9、句点、连字符、下划线,不能以特殊字符开头。最长 36 字符。 |
name | body | string | 是 | — | 提供商名称。 |
host | body | string | 是 | — | SMTP hosts. Either a single hostname or multiple semicolon-delimited hostnames. You can also specify a different port for each host such as smtp1.example.com:25;smtp2.example.com. You can also specify encryption type, for example: tls://smtp1.example.com:587;ssl://smtp2.example.com:465". Hosts will be tried in order. |
port | body | integer | 否 | — | SMTP 端口。 |
username | body | string | 否 | — | 认证用户名。 |
password | body | string | 否 | — | 认证密码。 |
encryption | body | string | 否 | none / ssl / tls | 加密方式:none(不加密)/ ssl / tls。 |
autoTLS | body | boolean | 否 | — | 是否启用 SMTP AutoTLS。 |
mailer | body | string | 否 | — | X-Mailer 请求头的值。 |
fromName | body | string | 否 | — | 发件人名称。 |
fromEmail | body | string | 否 | — | 发件人邮箱。 |
replyToName | body | string | 否 | — | 邮件 Reply-To 名称。默认取发件人名称。 |
replyToEmail | body | string | 否 | — | 邮件 Reply-To 邮箱。默认取发件人邮箱。 |
enabled | body | boolean | 否 | 可为 null | 是否启用。 |
输出:201,模型 provider(完整字段见前文),关键字段:
| 字段 | 类型 | 说明 |
|---|---|---|
$id | string | 提供商 ID。 |
$createdAt | string | 提供商创建时间(ISO 8601)。 |
$updatedAt | string | 提供商更新时间(ISO 8601)。 |
name | string | 提供商实例名称。 |
provider | string | 提供商服务标识。 |
enabled | boolean | 提供商是否启用。 |
type | string | 提供商通道类型。 |
credentials | object | 提供商凭证;字段和响应内容因提供商及部署配置而异。 |
options | object | 提供商选项。 |
调用示例:
curl -X POST "https://<your-endpoint>/v1/messaging/providers/smtp" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>" \
-H "Content-Type: application/json" \
-d '{
"providerId": "smtp-main",
"name": "SMTP",
"host": "smtp.example.com",
"port": 587,
"username": "postmaster@example.com",
"password": "smtp-password",
"encryption": "none",
"autoTLS": true,
"mailer": "AppBase",
"fromName": "AppBase"
}'响应字段节选(省略与该操作无关的字段):
{
"$id": "smtp-main",
"$createdAt": "2020-10-15T06:38:00.000+00:00",
"$updatedAt": "2020-10-15T06:38:00.000+00:00",
"name": "SMTP",
"provider": "smtp",
"enabled": true,
"type": "email"
}PATCH /v1/messaging/providers/smtp/{providerId}
更新 SMTP 提供商。该端点在 spec 中标记为 deprecated(v2.6.0 仍可用,SDK 保留对应方法)。(scope providers.write。SDK:Providers.updateSmtpProvider。)
输入(application/json)
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
name | body | string | 否 | — | 提供商名称。 |
host | body | string | 否 | — | SMTP hosts. Either a single hostname or multiple semicolon-delimited hostnames. You can also specify a different port for each host such as smtp1.example.com:25;smtp2.example.com. You can also specify encryption type, for example: tls://smtp1.example.com:587;ssl://smtp2.example.com:465". Hosts will be tried in order. |
port | body | integer | 否 | 可为 null | SMTP 端口。 |
username | body | string | 否 | — | 认证用户名。 |
password | body | string | 否 | — | 认证密码。 |
encryption | body | string | 否 | none / ssl / tls | 加密方式:ssl / tls。 |
autoTLS | body | boolean | 否 | 可为 null | 是否启用 SMTP AutoTLS。 |
mailer | body | string | 否 | — | X-Mailer 请求头的值。 |
fromName | body | string | 否 | — | 发件人名称。 |
fromEmail | body | string | 否 | — | 发件人邮箱。 |
replyToName | body | string | 否 | — | 邮件 Reply-To 名称。默认取发件人名称。 |
replyToEmail | body | string | 否 | — | 邮件 Reply-To 邮箱。默认取发件人邮箱。 |
enabled | body | boolean | 否 | 可为 null | 是否启用。 |
providerId | path | string | 是 | — | 提供商 ID。 |
输出:200,模型 provider(完整字段见前文),关键字段:
| 字段 | 类型 | 说明 |
|---|---|---|
$id | string | 提供商 ID。 |
$createdAt | string | 提供商创建时间(ISO 8601)。 |
$updatedAt | string | 提供商更新时间(ISO 8601)。 |
name | string | 提供商实例名称。 |
provider | string | 提供商服务标识。 |
enabled | boolean | 提供商是否启用。 |
type | string | 提供商通道类型。 |
credentials | object | 提供商凭证;字段和响应内容因提供商及部署配置而异。 |
options | object | 提供商选项。 |
调用示例:
curl -X PATCH "https://<your-endpoint>/v1/messaging/providers/smtp/<PROVIDER_ID>" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>" \
-H "Content-Type: application/json" \
-d '{
"name": "SMTP",
"host": "smtp.example.com",
"port": 587,
"username": "postmaster@example.com",
"password": "smtp-password",
"encryption": "none",
"autoTLS": true,
"mailer": "AppBase",
"fromName": "AppBase",
"fromEmail": "noreply@example.com"
}'响应字段节选(省略与该操作无关的字段):
{
"$id": "66f1a2b3c4d5e6f7",
"$createdAt": "2020-10-15T06:38:00.000+00:00",
"$updatedAt": "2020-10-15T06:38:00.000+00:00",
"name": "SMTP",
"provider": "smtp",
"enabled": true,
"type": "email"
}POST /v1/messaging/providers/telesign
创建 Telesign 短信提供商(scope providers.write。SDK:Providers.createTelesignProvider。)
输入(application/json)
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
providerId | body | string | 是 | — | 提供商 ID。可自定义,或用 SDK 的 ID.unique() 生成;仅允许 a-z、A-Z、0-9、句点、连字符、下划线,不能以特殊字符开头。最长 36 字符。 |
name | body | string | 是 | — | 提供商名称。 |
from | body | string | 否 | — | 发件人手机号,须带国家码的 + 前缀,如 +16175551212。 |
customerId | body | string | 否 | — | Telesign 客户 ID。 |
apiKey | body | string | 否 | — | Telesign API Key。 |
enabled | body | boolean | 否 | 可为 null | 是否启用。 |
输出:201,模型 provider(完整字段见前文),关键字段:
| 字段 | 类型 | 说明 |
|---|---|---|
$id | string | 提供商 ID。 |
$createdAt | string | 提供商创建时间(ISO 8601)。 |
$updatedAt | string | 提供商更新时间(ISO 8601)。 |
name | string | 提供商实例名称。 |
provider | string | 提供商服务标识。 |
enabled | boolean | 提供商是否启用。 |
type | string | 提供商通道类型。 |
credentials | object | 提供商凭证;字段和响应内容因提供商及部署配置而异。 |
options | object | 提供商选项。 |
调用示例:
curl -X POST "https://<your-endpoint>/v1/messaging/providers/telesign" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>" \
-H "Content-Type: application/json" \
-d '{
"providerId": "telesign-main",
"name": "TELESIGN",
"from": "+16175551212",
"customerId": "FFFFFFFF-1111-2222-3333-444444444444",
"apiKey": "key-1234567890abcdef",
"enabled": true
}'响应字段节选(省略与该操作无关的字段):
{
"$id": "telesign-main",
"$createdAt": "2020-10-15T06:38:00.000+00:00",
"$updatedAt": "2020-10-15T06:38:00.000+00:00",
"name": "TELESIGN",
"provider": "telesign",
"enabled": true,
"type": "sms"
}PATCH /v1/messaging/providers/telesign/{providerId}
更新 Telesign 提供商(scope providers.write。SDK:Providers.updateTelesignProvider。)
输入(application/json)
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
name | body | string | 否 | — | 提供商名称。 |
enabled | body | boolean | 否 | 可为 null | 是否启用。 |
customerId | body | string | 否 | — | Telesign 客户 ID。 |
apiKey | body | string | 否 | — | Telesign API Key。 |
from | body | string | 否 | — | 发信号码。 |
providerId | path | string | 是 | — | 提供商 ID。 |
输出:200,模型 provider(完整字段见前文),关键字段:
| 字段 | 类型 | 说明 |
|---|---|---|
$id | string | 提供商 ID。 |
$createdAt | string | 提供商创建时间(ISO 8601)。 |
$updatedAt | string | 提供商更新时间(ISO 8601)。 |
name | string | 提供商实例名称。 |
provider | string | 提供商服务标识。 |
enabled | boolean | 提供商是否启用。 |
type | string | 提供商通道类型。 |
credentials | object | 提供商凭证;字段和响应内容因提供商及部署配置而异。 |
options | object | 提供商选项。 |
调用示例:
curl -X PATCH "https://<your-endpoint>/v1/messaging/providers/telesign/<PROVIDER_ID>" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>" \
-H "Content-Type: application/json" \
-d '{
"name": "TELESIGN",
"enabled": true,
"customerId": "FFFFFFFF-1111-2222-3333-444444444444",
"apiKey": "key-1234567890abcdef",
"from": "+16175551212"
}'响应字段节选(省略与该操作无关的字段):
{
"$id": "66f1a2b3c4d5e6f7",
"$createdAt": "2020-10-15T06:38:00.000+00:00",
"$updatedAt": "2020-10-15T06:38:00.000+00:00",
"name": "TELESIGN",
"provider": "telesign",
"enabled": true,
"type": "sms"
}POST /v1/messaging/providers/textmagic
创建 Textmagic 短信提供商(scope providers.write。SDK:Providers.createTextmagicProvider。)
输入(application/json)
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
providerId | body | string | 是 | — | 提供商 ID。可自定义,或用 SDK 的 ID.unique() 生成;仅允许 a-z、A-Z、0-9、句点、连字符、下划线,不能以特殊字符开头。最长 36 字符。 |
name | body | string | 是 | — | 提供商名称。 |
from | body | string | 否 | — | 发件人手机号,须带国家码的 + 前缀,如 +16175551212。 |
username | body | string | 否 | — | Textmagic 用户名。 |
apiKey | body | string | 否 | — | Textmagic API Key。 |
enabled | body | boolean | 否 | 可为 null | 是否启用。 |
输出:201,模型 provider(完整字段见前文),关键字段:
| 字段 | 类型 | 说明 |
|---|---|---|
$id | string | 提供商 ID。 |
$createdAt | string | 提供商创建时间(ISO 8601)。 |
$updatedAt | string | 提供商更新时间(ISO 8601)。 |
name | string | 提供商实例名称。 |
provider | string | 提供商服务标识。 |
enabled | boolean | 提供商是否启用。 |
type | string | 提供商通道类型。 |
credentials | object | 提供商凭证;字段和响应内容因提供商及部署配置而异。 |
options | object | 提供商选项。 |
调用示例:
curl -X POST "https://<your-endpoint>/v1/messaging/providers/textmagic" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>" \
-H "Content-Type: application/json" \
-d '{
"providerId": "textmagic-main",
"name": "TEXTMAGIC",
"from": "+16175551212",
"username": "postmaster@example.com",
"apiKey": "key-1234567890abcdef",
"enabled": true
}'响应字段节选(省略与该操作无关的字段):
{
"$id": "textmagic-main",
"$createdAt": "2020-10-15T06:38:00.000+00:00",
"$updatedAt": "2020-10-15T06:38:00.000+00:00",
"name": "TEXTMAGIC",
"provider": "textmagic",
"enabled": true,
"type": "sms"
}PATCH /v1/messaging/providers/textmagic/{providerId}
更新 Textmagic 提供商(scope providers.write。SDK:Providers.updateTextmagicProvider。)
输入(application/json)
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
name | body | string | 否 | — | 提供商名称。 |
enabled | body | boolean | 否 | 可为 null | 是否启用。 |
username | body | string | 否 | — | Textmagic 用户名。 |
apiKey | body | string | 否 | — | Textmagic API Key。 |
from | body | string | 否 | — | 发信号码。 |
providerId | path | string | 是 | — | 提供商 ID。 |
输出:200,模型 provider(完整字段见前文),关键字段:
| 字段 | 类型 | 说明 |
|---|---|---|
$id | string | 提供商 ID。 |
$createdAt | string | 提供商创建时间(ISO 8601)。 |
$updatedAt | string | 提供商更新时间(ISO 8601)。 |
name | string | 提供商实例名称。 |
provider | string | 提供商服务标识。 |
enabled | boolean | 提供商是否启用。 |
type | string | 提供商通道类型。 |
credentials | object | 提供商凭证;字段和响应内容因提供商及部署配置而异。 |
options | object | 提供商选项。 |
调用示例:
curl -X PATCH "https://<your-endpoint>/v1/messaging/providers/textmagic/<PROVIDER_ID>" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>" \
-H "Content-Type: application/json" \
-d '{
"name": "TEXTMAGIC",
"enabled": true,
"username": "postmaster@example.com",
"apiKey": "key-1234567890abcdef",
"from": "+16175551212"
}'响应字段节选(省略与该操作无关的字段):
{
"$id": "66f1a2b3c4d5e6f7",
"$createdAt": "2020-10-15T06:38:00.000+00:00",
"$updatedAt": "2020-10-15T06:38:00.000+00:00",
"name": "TEXTMAGIC",
"provider": "textmagic",
"enabled": true,
"type": "sms"
}POST /v1/messaging/providers/twilio
创建 Twilio 短信提供商(scope providers.write。SDK:Providers.createTwilioProvider。)
输入(application/json)
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
providerId | body | string | 是 | — | 提供商 ID。可自定义,或用 SDK 的 ID.unique() 生成;仅允许 a-z、A-Z、0-9、句点、连字符、下划线,不能以特殊字符开头。最长 36 字符。 |
name | body | string | 是 | — | 提供商名称。 |
from | body | string | 否 | — | 发件人手机号,须带国家码的 + 前缀,如 +16175551212。 |
accountSid | body | string | 否 | — | Twilio Account SID。 |
authToken | body | string | 否 | — | Twilio Auth Token。 |
enabled | body | boolean | 否 | 可为 null | 是否启用。 |
输出:201,模型 provider(完整字段见前文),关键字段:
| 字段 | 类型 | 说明 |
|---|---|---|
$id | string | 提供商 ID。 |
$createdAt | string | 提供商创建时间(ISO 8601)。 |
$updatedAt | string | 提供商更新时间(ISO 8601)。 |
name | string | 提供商实例名称。 |
provider | string | 提供商服务标识。 |
enabled | boolean | 提供商是否启用。 |
type | string | 提供商通道类型。 |
credentials | object | 提供商凭证;字段和响应内容因提供商及部署配置而异。 |
options | object | 提供商选项。 |
调用示例:
curl -X POST "https://<your-endpoint>/v1/messaging/providers/twilio" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>" \
-H "Content-Type: application/json" \
-d '{
"providerId": "twilio-main",
"name": "TWILIO",
"from": "+16175551212",
"accountSid": "ACb1c2d3e4f5a6b7c8d9e0f1a2b3c4d5e6f",
"authToken": "authtoken1234567890abcdef",
"enabled": true
}'响应字段节选(省略与该操作无关的字段):
{
"$id": "twilio-main",
"$createdAt": "2020-10-15T06:38:00.000+00:00",
"$updatedAt": "2020-10-15T06:38:00.000+00:00",
"name": "TWILIO",
"provider": "twilio",
"enabled": true,
"type": "sms"
}PATCH /v1/messaging/providers/twilio/{providerId}
更新 Twilio 提供商(scope providers.write。SDK:Providers.updateTwilioProvider。)
输入(application/json)
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
name | body | string | 否 | — | 提供商名称。 |
enabled | body | boolean | 否 | 可为 null | 是否启用。 |
accountSid | body | string | 否 | — | Twilio Account SID。 |
authToken | body | string | 否 | — | Twilio Auth Token。 |
from | body | string | 否 | — | 发信号码。 |
providerId | path | string | 是 | — | 提供商 ID。 |
输出:200,模型 provider(完整字段见前文),关键字段:
| 字段 | 类型 | 说明 |
|---|---|---|
$id | string | 提供商 ID。 |
$createdAt | string | 提供商创建时间(ISO 8601)。 |
$updatedAt | string | 提供商更新时间(ISO 8601)。 |
name | string | 提供商实例名称。 |
provider | string | 提供商服务标识。 |
enabled | boolean | 提供商是否启用。 |
type | string | 提供商通道类型。 |
credentials | object | 提供商凭证;字段和响应内容因提供商及部署配置而异。 |
options | object | 提供商选项。 |
调用示例:
curl -X PATCH "https://<your-endpoint>/v1/messaging/providers/twilio/<PROVIDER_ID>" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>" \
-H "Content-Type: application/json" \
-d '{
"name": "TWILIO",
"enabled": true,
"accountSid": "ACb1c2d3e4f5a6b7c8d9e0f1a2b3c4d5e6f",
"authToken": "authtoken1234567890abcdef",
"from": "+16175551212"
}'响应字段节选(省略与该操作无关的字段):
{
"$id": "66f1a2b3c4d5e6f7",
"$createdAt": "2020-10-15T06:38:00.000+00:00",
"$updatedAt": "2020-10-15T06:38:00.000+00:00",
"name": "TWILIO",
"provider": "twilio",
"enabled": true,
"type": "sms"
}POST /v1/messaging/providers/vonage
创建 Vonage 短信提供商(scope providers.write。SDK:Providers.createVonageProvider。)
输入(application/json)
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
providerId | body | string | 是 | — | 提供商 ID。可自定义,或用 SDK 的 ID.unique() 生成;仅允许 a-z、A-Z、0-9、句点、连字符、下划线,不能以特殊字符开头。最长 36 字符。 |
name | body | string | 是 | — | 提供商名称。 |
from | body | string | 否 | — | 发件人手机号,须带国家码的 + 前缀,如 +16175551212。 |
apiKey | body | string | 否 | — | Vonage API Key。 |
apiSecret | body | string | 否 | — | Vonage API Secret。 |
enabled | body | boolean | 否 | 可为 null | 是否启用。 |
输出:201,模型 provider(完整字段见前文),关键字段:
| 字段 | 类型 | 说明 |
|---|---|---|
$id | string | 提供商 ID。 |
$createdAt | string | 提供商创建时间(ISO 8601)。 |
$updatedAt | string | 提供商更新时间(ISO 8601)。 |
name | string | 提供商实例名称。 |
provider | string | 提供商服务标识。 |
enabled | boolean | 提供商是否启用。 |
type | string | 提供商通道类型。 |
credentials | object | 提供商凭证;字段和响应内容因提供商及部署配置而异。 |
options | object | 提供商选项。 |
调用示例:
curl -X POST "https://<your-endpoint>/v1/messaging/providers/vonage" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>" \
-H "Content-Type: application/json" \
-d '{
"providerId": "vonage-main",
"name": "VONAGE",
"from": "+16175551212",
"apiKey": "key-1234567890abcdef",
"apiSecret": "apisecret1234567890abcdef",
"enabled": true
}'响应字段节选(省略与该操作无关的字段):
{
"$id": "vonage-main",
"$createdAt": "2020-10-15T06:38:00.000+00:00",
"$updatedAt": "2020-10-15T06:38:00.000+00:00",
"name": "VONAGE",
"provider": "vonage",
"enabled": true,
"type": "sms"
}PATCH /v1/messaging/providers/vonage/{providerId}
更新 Vonage 提供商(scope providers.write。SDK:Providers.updateVonageProvider。)
输入(application/json)
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
name | body | string | 否 | — | 提供商名称。 |
enabled | body | boolean | 否 | 可为 null | 是否启用。 |
apiKey | body | string | 否 | — | Vonage API Key。 |
apiSecret | body | string | 否 | — | Vonage API Secret。 |
from | body | string | 否 | — | 发信号码。 |
providerId | path | string | 是 | — | 提供商 ID。 |
输出:200,模型 provider(完整字段见前文),关键字段:
| 字段 | 类型 | 说明 |
|---|---|---|
$id | string | 提供商 ID。 |
$createdAt | string | 提供商创建时间(ISO 8601)。 |
$updatedAt | string | 提供商更新时间(ISO 8601)。 |
name | string | 提供商实例名称。 |
provider | string | 提供商服务标识。 |
enabled | boolean | 提供商是否启用。 |
type | string | 提供商通道类型。 |
credentials | object | 提供商凭证;字段和响应内容因提供商及部署配置而异。 |
options | object | 提供商选项。 |
调用示例:
curl -X PATCH "https://<your-endpoint>/v1/messaging/providers/vonage/<PROVIDER_ID>" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>" \
-H "Content-Type: application/json" \
-d '{
"name": "VONAGE",
"enabled": true,
"apiKey": "key-1234567890abcdef",
"apiSecret": "apisecret1234567890abcdef",
"from": "+16175551212"
}'响应字段节选(省略与该操作无关的字段):
{
"$id": "66f1a2b3c4d5e6f7",
"$createdAt": "2020-10-15T06:38:00.000+00:00",
"$updatedAt": "2020-10-15T06:38:00.000+00:00",
"name": "VONAGE",
"provider": "vonage",
"enabled": true,
"type": "sms"
}GET /v1/messaging/providers/{providerId}
按 ID 读取提供商详情;响应可能包含敏感配置,请避免记录或泄露(scope providers.read。SDK:Providers.getProvider。)
输入
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
providerId | path | string | 是 | — | 提供商 ID。 |
输出:200,模型 provider(完整字段见前文),关键字段:
| 字段 | 类型 | 说明 |
|---|---|---|
$id | string | 提供商 ID。 |
$createdAt | string | 提供商创建时间(ISO 8601)。 |
$updatedAt | string | 提供商更新时间(ISO 8601)。 |
name | string | 提供商实例名称。 |
provider | string | 提供商服务标识。 |
enabled | boolean | 提供商是否启用。 |
type | string | 提供商通道类型。 |
credentials | object | 提供商凭证;字段和响应内容因提供商及部署配置而异。 |
options | object | 提供商选项。 |
调用示例:
curl "https://<your-endpoint>/v1/messaging/providers/<PROVIDER_ID>" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>"响应字段节选:
{
"$id": "66f1a2b3c4d5e6f7",
"$createdAt": "2020-10-15T06:38:00.000+00:00",
"$updatedAt": "2020-10-15T06:38:00.000+00:00",
"name": "Mailgun",
"provider": "mailgun",
"enabled": true,
"type": "email"
}DELETE /v1/messaging/providers/{providerId}
删除提供商:未发送消息会因缺少可用提供商而投递失败(scope providers.write。SDK:Providers.deleteProvider。)
输入
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
providerId | path | string | 是 | — | 提供商 ID。 |
输出:204 无响应体。
调用示例:
curl -X DELETE "https://<your-endpoint>/v1/messaging/providers/<PROVIDER_ID>" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>"响应示例:
_二进制流或无响应体(见输出说明)。_
GET /v1/messaging/providers/{providerId}/logs
列出该提供商的发送日志(仅支持 limit/offset 分页)(scope providers.read。SDK:Providers.listProviderLogs。)
输入
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
providerId | path | string | 是 | — | 提供商 ID。 |
queries | query | string[] | 否 | 默认 [] | 查询字符串数组,由 SDK 的 Query 构造器生成(形如 limit(25)、equal("name","x"));仅支持 limit / offset 两个方法。 |
total | query | boolean | 否 | 默认 true | 设为 false 时跳过总数计算,返回的 total 固定为 0。 |
输出:200,模型 logList:total(匹配总数,total=false 时不计算)+ logs[](当前页数据)。
元素模型 log 关键字段:
| 字段 | 类型 | 说明 |
|---|---|---|
event | string | 事件名。 |
userId | string | 触发该日志的用户 ID。被代理(impersonation)时记录代理发起者而非被代理用户。 |
userEmail | string | 触发该日志的用户邮箱。 |
mode | string | 事件触发时的 API 模式(admin/key 等)。 |
ip | string | 事件发生时的来源 IP。 |
time | string | 日志创建时间(ISO 8601)。 |
clientName | string | 客户端名称。 |
countryName | string | 国家/地区名称。 |
调用示例:
curl -G "https://<your-endpoint>/v1/messaging/providers/<PROVIDER_ID>/logs" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>" \
--data-urlencode "queries[]=limit(25)"响应示例:
{
"total": 5,
"logs": ""
}主题与订阅者
GET /v1/messaging/topics
分页列出项目内全部主题(scope topics.read。SDK:Topics.listTopics。)
输入
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
queries | query | string[] | 否 | 默认 [] | 查询字符串数组,由 SDK 的 Query 构造器生成(形如 limit(25)、equal("name","x"));支持过滤、排序、分页(limit / cursorAfter / cursorBefore);可过滤属性:name、description、emailTotal、smsTotal、pushTotal。最多 100 条、每条最长 4096 字符。 |
search | query | string | 否 | — | 搜索词,模糊过滤列表结果。最长 256 字符。 |
total | query | boolean | 否 | 默认 true | 设为 false 时跳过总数计算,返回的 total 固定为 0。 |
输出:200,模型 topicList:total(匹配总数,total=false 时不计算)+ topics[](当前页数据)。
元素模型 topic 关键字段:
| 字段 | 类型 | 说明 |
|---|---|---|
$id | string | 主题 ID。 |
$createdAt | string | 主题创建时间(ISO 8601)。 |
$updatedAt | string | 主题更新时间(ISO 8601)。 |
name | string | 主题名称。 |
emailTotal | integer | 订阅该主题的邮件目标数。 |
smsTotal | integer | 订阅该主题的短信目标数。 |
pushTotal | integer | 订阅该主题的推送目标数。 |
subscribe | string[] | 可订阅角色。 |
调用示例:
curl -G "https://<your-endpoint>/v1/messaging/topics" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>" \
--data-urlencode "queries[]=limit(25)" \
--data-urlencode "search=welcome"响应示例:
{
"total": 5,
"topics": [
{
"$id": "66f1a2b3c4d5e6f7",
"$createdAt": "2020-10-15T06:38:00.000+00:00",
"$updatedAt": "2020-10-15T06:38:00.000+00:00",
"name": "events",
"emailTotal": 100,
"smsTotal": 100,
"pushTotal": 100,
"subscribe": [
"users"
]
}
]
}POST /v1/messaging/topics
创建主题:subscribe 控制哪些角色可以订阅(默认全部用户)(scope topics.write。SDK:Topics.createTopic。)
输入(application/json)
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
topicId | body | string | 是 | — | 主题 ID。可自定义新 ID。 |
name | body | string | 是 | — | 主题名称。 |
subscribe | body | string[] | 否 | — | 拥有订阅权限的角色数组。默认所有用户都可订阅。最多 100 个角色,每个最长 64 字符。 |
输出:201,模型 topic,字段:
| 字段 | 类型 | 说明 |
|---|---|---|
$id | string | 主题 ID。 |
$createdAt | string | 主题创建时间(ISO 8601)。 |
$updatedAt | string | 主题更新时间(ISO 8601)。 |
name | string | 主题名称。 |
emailTotal | integer | 订阅该主题的邮件目标数。 |
smsTotal | integer | 订阅该主题的短信目标数。 |
pushTotal | integer | 订阅该主题的推送目标数。 |
subscribe | string[] | 可订阅角色。 |
调用示例:
curl -X POST "https://<your-endpoint>/v1/messaging/topics" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>" \
-H "Content-Type: application/json" \
-d '{
"topicId": "announcements",
"name": "Welcome Email",
"subscribe": [
"users"
]
}'响应示例:
{
"$id": "66f1a2b3c4d5e6f7",
"$createdAt": "2020-10-15T06:38:00.000+00:00",
"$updatedAt": "2020-10-15T06:38:00.000+00:00",
"name": "events",
"emailTotal": 100,
"smsTotal": 100,
"pushTotal": 100,
"subscribe": [
"users"
]
}GET /v1/messaging/topics/{topicId}
读取主题详情与各通道订阅计数(scope topics.read。SDK:Topics.getTopic。)
输入
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
topicId | path | string | 是 | — | 主题 ID。 |
输出:200,模型 topic(完整字段见前文),关键字段:
| 字段 | 类型 | 说明 |
|---|---|---|
$id | string | 主题 ID。 |
$createdAt | string | 主题创建时间(ISO 8601)。 |
$updatedAt | string | 主题更新时间(ISO 8601)。 |
name | string | 主题名称。 |
emailTotal | integer | 订阅该主题的邮件目标数。 |
smsTotal | integer | 订阅该主题的短信目标数。 |
pushTotal | integer | 订阅该主题的推送目标数。 |
subscribe | string[] | 可订阅角色。 |
调用示例:
curl "https://<your-endpoint>/v1/messaging/topics/<TOPIC_ID>" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>"响应示例:
{
"$id": "66f1a2b3c4d5e6f7",
"$createdAt": "2020-10-15T06:38:00.000+00:00",
"$updatedAt": "2020-10-15T06:38:00.000+00:00",
"name": "events",
"emailTotal": 100,
"smsTotal": 100,
"pushTotal": 100,
"subscribe": [
"users"
]
}PATCH /v1/messaging/topics/{topicId}
更新主题名称与可订阅角色(scope topics.write。SDK:Topics.updateTopic。)
输入(application/json)
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
name | body | string | 否 | 可为 null | 主题名称。 |
subscribe | body | string[] | 否 | 可为 null | 拥有订阅权限的角色数组。默认所有用户都可订阅。最多 100 个角色,每个最长 64 字符。 |
topicId | path | string | 是 | — | 主题 ID。 |
输出:200,模型 topic(完整字段见前文),关键字段:
| 字段 | 类型 | 说明 |
|---|---|---|
$id | string | 主题 ID。 |
$createdAt | string | 主题创建时间(ISO 8601)。 |
$updatedAt | string | 主题更新时间(ISO 8601)。 |
name | string | 主题名称。 |
emailTotal | integer | 订阅该主题的邮件目标数。 |
smsTotal | integer | 订阅该主题的短信目标数。 |
pushTotal | integer | 订阅该主题的推送目标数。 |
subscribe | string[] | 可订阅角色。 |
调用示例:
curl -X PATCH "https://<your-endpoint>/v1/messaging/topics/<TOPIC_ID>" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>" \
-H "Content-Type: application/json" \
-d '{
"subscribe": [
"users"
]
}'响应示例:
{
"$id": "66f1a2b3c4d5e6f7",
"$createdAt": "2020-10-15T06:38:00.000+00:00",
"$updatedAt": "2020-10-15T06:38:00.000+00:00",
"name": "events",
"emailTotal": 100,
"smsTotal": 100,
"pushTotal": 100,
"subscribe": [
"users"
]
}DELETE /v1/messaging/topics/{topicId}
删除主题及其订阅关系(scope topics.write。SDK:Topics.deleteTopic。)
输入
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
topicId | path | string | 是 | — | 主题 ID。 |
输出:204 无响应体。
调用示例:
curl -X DELETE "https://<your-endpoint>/v1/messaging/topics/<TOPIC_ID>" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>"响应示例:
_二进制流或无响应体(见输出说明)。_
GET /v1/messaging/topics/{topicId}/logs
列出该主题的投递日志(仅支持 limit/offset 分页)(scope topics.read。SDK:Topics.listTopicLogs。)
输入
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
topicId | path | string | 是 | — | 主题 ID。 |
queries | query | string[] | 否 | 默认 [] | 查询字符串数组,由 SDK 的 Query 构造器生成(形如 limit(25)、equal("name","x"));仅支持 limit / offset 两个方法。 |
total | query | boolean | 否 | 默认 true | 设为 false 时跳过总数计算,返回的 total 固定为 0。 |
输出:200,模型 logList:total(匹配总数,total=false 时不计算)+ logs[](当前页数据)。
元素模型 log 关键字段:
| 字段 | 类型 | 说明 |
|---|---|---|
event | string | 事件名。 |
userId | string | 触发该日志的用户 ID。被代理(impersonation)时记录代理发起者而非被代理用户。 |
userEmail | string | 触发该日志的用户邮箱。 |
mode | string | 事件触发时的 API 模式(admin/key 等)。 |
ip | string | 事件发生时的来源 IP。 |
time | string | 日志创建时间(ISO 8601)。 |
clientName | string | 客户端名称。 |
countryName | string | 国家/地区名称。 |
调用示例:
curl -G "https://<your-endpoint>/v1/messaging/topics/<TOPIC_ID>/logs" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>" \
--data-urlencode "queries[]=limit(25)"响应示例:
{
"total": 5,
"logs": ""
}GET /v1/messaging/topics/{topicId}/subscribers
分页列出主题下的订阅者(scope subscribers.read。SDK:Subscribers.listSubscribers。)
输入
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
topicId | path | string | 是 | — | 要订阅的主题 ID。 |
queries | query | string[] | 否 | 默认 [] | 查询字符串数组,由 SDK 的 Query 构造器生成(形如 limit(25)、equal("name","x"));支持过滤、排序、分页(limit / cursorAfter / cursorBefore);可过滤属性:targetId、topicId、userId、providerType。最多 100 条、每条最长 4096 字符。 |
search | query | string | 否 | — | 搜索词,模糊过滤列表结果。最长 256 字符。 |
total | query | boolean | 否 | 默认 true | 设为 false 时跳过总数计算,返回的 total 固定为 0。 |
输出:200,模型 subscriberList:total(匹配总数,total=false 时不计算)+ subscribers[](当前页数据)。
元素模型 subscriber 关键字段:
| 字段 | 类型 | 说明 |
|---|---|---|
$id | string | 订阅者 ID。 |
$createdAt | string | 订阅创建时间(ISO 8601)。 |
$updatedAt | string | 订阅更新时间(ISO 8601)。 |
targetId | string | 目标 ID。 |
target | object | 消息目标对象。 |
topicId | string | 主题 ID。 |
调用示例:
curl -G "https://<your-endpoint>/v1/messaging/topics/<TOPIC_ID>/subscribers" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>" \
--data-urlencode "queries[]=limit(25)" \
--data-urlencode "search=welcome"响应示例:
{
"total": 5,
"subscribers": [
{
"$id": "66f1a2b3c4d5e6f7",
"$createdAt": "2020-10-15T06:38:00.000+00:00",
"$updatedAt": "2020-10-15T06:38:00.000+00:00",
"targetId": "259125845563242502",
"target": {
"$id": "259125845563242502",
"$createdAt": "2020-10-15T06:38:00.000+00:00",
"$updatedAt": "2020-10-15T06:38:00.000+00:00",
"providerType": "email",
"providerId": "259125845563242502",
"name": "ageon-app-email",
"identifier": "random-mail@email.org",
"userId": "5e5ea5c16897e"
},
"userId": "5e5ea5c16897e",
"userName": "Aegon Targaryen",
"topicId": "259125845563242502",
"providerType": "email"
}
]
}POST /v1/messaging/topics/{topicId}/subscribers
为目标(target)创建主题订阅:targetId 必须属于某个已存在用户的消息目标(scope subscribers.write。SDK:Subscribers.createSubscriber。)
输入(application/json)
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
subscriberId | body | string | 是 | — | 订阅者 ID。可自定义新 ID。 |
targetId | body | string | 是 | — | 要关联到该主题的目标 ID(来自 users 的消息目标)。 |
topicId | path | string | 是 | — | 要订阅的主题 ID。 |
输出:201,模型 subscriber,字段:
| 字段 | 类型 | 说明 |
|---|---|---|
$id | string | 订阅者 ID。 |
$createdAt | string | 订阅创建时间(ISO 8601)。 |
$updatedAt | string | 订阅更新时间(ISO 8601)。 |
targetId | string | 目标 ID。 |
target | object | 消息目标对象。 |
userId | string | 订阅者关联的用户 ID。 |
userName | string | 订阅者关联的用户名。 |
topicId | string | 主题 ID。 |
providerType | string | 目标通道类型:email / sms / push。 |
调用示例:
curl -X POST "https://<your-endpoint>/v1/messaging/topics/<TOPIC_ID>/subscribers" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>" \
-H "Content-Type: application/json" \
-d '{
"subscriberId": "66f1a2b3c4d5e6f7",
"targetId": "66f1a2b3c4d5e6f7"
}'响应示例:
{
"$id": "66f1a2b3c4d5e6f7",
"$createdAt": "2020-10-15T06:38:00.000+00:00",
"$updatedAt": "2020-10-15T06:38:00.000+00:00",
"targetId": "259125845563242502",
"target": {
"$id": "259125845563242502",
"$createdAt": "2020-10-15T06:38:00.000+00:00",
"$updatedAt": "2020-10-15T06:38:00.000+00:00",
"providerType": "email",
"providerId": "259125845563242502",
"name": "ageon-app-email",
"identifier": "random-mail@email.org",
"userId": "5e5ea5c16897e"
},
"userId": "5e5ea5c16897e",
"userName": "Aegon Targaryen",
"topicId": "259125845563242502",
"providerType": "email"
}GET /v1/messaging/topics/{topicId}/subscribers/{subscriberId}
读取单条订阅关系(scope subscribers.read。SDK:Subscribers.getSubscriber。)
输入
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
topicId | path | string | 是 | — | 要订阅的主题 ID。 |
subscriberId | path | string | 是 | — | 订阅者 ID。 |
输出:200,模型 subscriber(完整字段见前文),关键字段:
| 字段 | 类型 | 说明 |
|---|---|---|
$id | string | 订阅者 ID。 |
$createdAt | string | 订阅创建时间(ISO 8601)。 |
$updatedAt | string | 订阅更新时间(ISO 8601)。 |
targetId | string | 目标 ID。 |
target | object | 消息目标对象。 |
topicId | string | 主题 ID。 |
调用示例:
curl "https://<your-endpoint>/v1/messaging/topics/<TOPIC_ID>/subscribers/<SUBSCRIBER_ID>" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>"响应示例:
{
"$id": "66f1a2b3c4d5e6f7",
"$createdAt": "2020-10-15T06:38:00.000+00:00",
"$updatedAt": "2020-10-15T06:38:00.000+00:00",
"targetId": "259125845563242502",
"target": {
"$id": "259125845563242502",
"$createdAt": "2020-10-15T06:38:00.000+00:00",
"$updatedAt": "2020-10-15T06:38:00.000+00:00",
"providerType": "email",
"providerId": "259125845563242502",
"name": "ageon-app-email",
"identifier": "random-mail@email.org",
"userId": "5e5ea5c16897e"
},
"userId": "5e5ea5c16897e",
"userName": "Aegon Targaryen",
"topicId": "259125845563242502",
"providerType": "email"
}DELETE /v1/messaging/topics/{topicId}/subscribers/{subscriberId}
退订:删除该订阅关系(scope subscribers.write。SDK:Subscribers.deleteSubscriber。)
输入
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
topicId | path | string | 是 | — | 要订阅的主题 ID。 |
subscriberId | path | string | 是 | — | 订阅者 ID。 |
输出:204 无响应体。
调用示例:
curl -X DELETE "https://<your-endpoint>/v1/messaging/topics/<TOPIC_ID>/subscribers/<SUBSCRIBER_ID>" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>"响应示例:
_二进制流或无响应体(见输出说明)。_
GET /v1/messaging/subscribers/{subscriberId}/logs
列出该订阅者相关的投递日志(仅支持 limit/offset 分页)(scope subscribers.read。SDK:Subscribers.listSubscriberLogs。)
输入
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
subscriberId | path | string | 是 | — | 订阅者 ID。 |
queries | query | string[] | 否 | 默认 [] | 查询字符串数组,由 SDK 的 Query 构造器生成(形如 limit(25)、equal("name","x"));仅支持 limit / offset 两个方法。 |
total | query | boolean | 否 | 默认 true | 设为 false 时跳过总数计算,返回的 total 固定为 0。 |
输出:200,模型 logList:total(匹配总数,total=false 时不计算)+ logs[](当前页数据)。
元素模型 log 关键字段:
| 字段 | 类型 | 说明 |
|---|---|---|
event | string | 事件名。 |
userId | string | 触发该日志的用户 ID。被代理(impersonation)时记录代理发起者而非被代理用户。 |
userEmail | string | 触发该日志的用户邮箱。 |
mode | string | 事件触发时的 API 模式(admin/key 等)。 |
ip | string | 事件发生时的来源 IP。 |
time | string | 日志创建时间(ISO 8601)。 |
clientName | string | 客户端名称。 |
countryName | string | 国家/地区名称。 |
调用示例:
curl -G "https://<your-endpoint>/v1/messaging/subscribers/<SUBSCRIBER_ID>/logs" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>" \
--data-urlencode "queries[]=limit(25)"响应示例:
{
"total": 5,
"logs": ""
}错误与边界
消息/提供商/主题/订阅者不存在:
404+message_not_found/provider_not_found/topic_not_found/subscriber_not_found;提供商重复:provider_already_exists。投递失败:消息
status=failed,失败明细在deliveryData与消息日志;已排期消息在发送前可改可删。附件与图片必须是
<BUCKET_ID>:<FILE_ID>复合 ID 且文件存在于 Storage;推送image仅接受 jpeg/png。未配置对应通道提供商时,消息会创建成功但投递失败——先建 provider 再发消息。
短信/邮件按提供商计费,群发前用
draft+ 小范围targets验证;scheduledAt必须是未来时间,精度到分钟。
与 Server SDK 的对应
| service.method | 端点 |
|---|---|
Messaging.listMessages / getMessage / deleteMessage | GET /messaging/messages、GET|DELETE .../messages/{messageId} |
Messaging.createEmail / updateEmail、createSms / updateSms、createPush / updatePush | POST|PATCH /messaging/messages/{email|sms|push} |
Messaging.listTargets / listMessageLogs | GET .../messages/{messageId}/targets、.../logs |
Messaging.listProviders / getProvider / deleteProvider / listProviderLogs | /messaging/providers* |
Messaging.createApnsProvider … createVonageProvider(11 种)、updateApnsProvider … updateVonageProvider | POST|PATCH /messaging/providers/{type} |
Messaging.listTopics / createTopic / getTopic / updateTopic / deleteTopic / listTopicLogs | /messaging/topics* |
Messaging.listSubscribers / createSubscriber / getSubscriber / deleteSubscriber / listSubscriberLogs | /messaging/topics/{topicId}/subscribers*、/messaging/subscribers/{subscriberId}/logs |