agentbase-docs

消息推送 API

统一消息面:消息提供商(provider:邮件/短信/推送通道)、主题(topic)与订阅者(subscriber)、草稿与排期消息(email / sms / push)的创建、修改与投递日志。

资源与基础路径

认证与权限

认证与请求头约定见 通用约定。本域 scope:messages.read / messages.write(消息)、providers.read / providers.write(提供商)、topics.read / topics.write(主题)、subscribers.read / subscribers.write(订阅者)。

端点清单

消息(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/apnsfcm`创建推送提供商(APNS / FCM)
`POST /messaging/providers/mailgunsendgridsmtpresend`创建邮件提供商
`POST /messaging/providers/twiliovonagetelesignmsg91textmagic`创建短信提供商
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订阅者投递日志

请求与响应

以下按端点逐个给出输入/输出规格、可复制的 curl 调用示例与响应示例。路径前缀 /v1;请求头 X-Appwrite-Project: <YOUR_PROJECT_ID> 与 X-Appwrite-Key: <YOUR_API_KEY> 对全部端点一致,示例中不再逐条解释。

消息

GET /v1/messaging/messages

分页列出项目内全部消息,可按状态、排期时间等过滤与关键词搜索(scope messages.read。SDK:Messages.listMessages。)

输入

参数位置类型必填默认/枚举说明
queriesquerystring[]否默认 []查询字符串数组,由 SDK 的 Query 构造器生成(形如 limit(25)、equal("name","x"));支持过滤、排序、分页(limit / cursorAfter / cursorBefore);可过滤属性:scheduledAt、deliveredAt、deliveredTotal、status、description、providerType。最多 100 条、每条最长 4096 字符。
searchquerystring否—搜索词,模糊过滤列表结果。最长 256 字符。
totalqueryboolean否默认 true设为 false 时跳过总数计算,返回的 total 固定为 0。

输出:200,模型 messageList:total(匹配总数,total=false 时不计算)+ messages[](当前页数据)。

元素模型 message 关键字段:

字段类型说明
$idstring消息 ID。
$createdAtstring消息创建时间(ISO 8601)。
$updatedAtstring消息更新时间(ISO 8601)。
providerTypestring消息通道类型(email / sms / push)。
topicsstring[]作为收件人的主题 ID 列表。
usersstring[]作为收件人的用户 ID 列表。
targetsstring[]作为收件人的目标 ID 列表。
scheduledAtstring消息计划发送时间。
deliveredAtstring消息实际投递时间。
deliveryErrorsstring[]投递错误列表(如有)。
deliveredTotalinteger已成功投递的收件人数。
dataobject消息数据。
statusstring投递状态。

调用示例:

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)

参数位置类型必填默认/枚举说明
messageIdbodystring是—消息 ID。可自定义,或用 SDK 的 ID.unique() 生成;仅允许 a-z、A-Z、0-9、句点、连字符、下划线,不能以特殊字符开头。最长 36 字符。
subjectbodystring是—邮件主题。
contentbodystring是—邮件正文。
topicsbodystring[]否—主题 ID 列表。
usersbodystring[]否—用户 ID 列表。
targetsbodystring[]否—目标 ID 列表。
ccbodystring[]否—抄送(CC)目标 ID 数组。
bccbodystring[]否—密送(BCC)目标 ID 数组。
attachmentsbodystring[]否—邮件附件的复合 ID 数组,格式为 <BUCKET_ID>:<FILE_ID>(文件须已在 Storage 上传)。
draftbodyboolean否—是否为草稿。
htmlbodyboolean否—正文是否为 HTML。
scheduledAtbodystring否可为 null消息排期发送时间(ISO 8601)。必须是未来时间。

输出:201,模型 message,字段:

字段类型说明
$idstring消息 ID。
$createdAtstring消息创建时间(ISO 8601)。
$updatedAtstring消息更新时间(ISO 8601)。
providerTypestring消息通道类型(email / sms / push)。
topicsstring[]作为收件人的主题 ID 列表。
usersstring[]作为收件人的用户 ID 列表。
targetsstring[]作为收件人的目标 ID 列表。
scheduledAtstring消息计划发送时间。
deliveredAtstring消息实际投递时间。
deliveryErrorsstring[]投递错误列表(如有)。
deliveredTotalinteger已成功投递的收件人数。
dataobject消息数据。
statusstring投递状态。

调用示例:

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

PATCH /v1/messaging/messages/email/{messageId}

更新邮件消息:仅 draft 状态可改;已进入 processing / sent / failed 的消息不可修改(scope messages.write。SDK:Messages.updateEmail。)

输入(application/json)

参数位置类型必填默认/枚举说明
topicsbodystring[]否可为 null主题 ID 列表。
usersbodystring[]否可为 null用户 ID 列表。
targetsbodystring[]否可为 null目标 ID 列表。
subjectbodystring否可为 null邮件主题。
contentbodystring否可为 null邮件正文。
draftbodyboolean否可为 null是否为草稿。
htmlbodyboolean否可为 null正文是否为 HTML。
ccbodystring[]否可为 null抄送(CC)目标 ID 数组。
bccbodystring[]否可为 null密送(BCC)目标 ID 数组。
scheduledAtbodystring否可为 null消息排期发送时间(ISO 8601)。必须是未来时间。
attachmentsbodystring[]否可为 null邮件附件的复合 ID 数组,格式为 <BUCKET_ID>:<FILE_ID>(文件须已在 Storage 上传)。
messageIdpathstring是—消息 ID。

输出:200,模型 message(完整字段见前文),关键字段:

字段类型说明
$idstring消息 ID。
$createdAtstring消息创建时间(ISO 8601)。
$updatedAtstring消息更新时间(ISO 8601)。
providerTypestring消息通道类型(email / sms / push)。
topicsstring[]作为收件人的主题 ID 列表。
usersstring[]作为收件人的用户 ID 列表。
targetsstring[]作为收件人的目标 ID 列表。
scheduledAtstring消息计划发送时间。
deliveredAtstring消息实际投递时间。
deliveryErrorsstring[]投递错误列表(如有)。
deliveredTotalinteger已成功投递的收件人数。
dataobject消息数据。
statusstring投递状态。

调用示例:

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)

参数位置类型必填默认/枚举说明
messageIdbodystring是—消息 ID。可自定义,或用 SDK 的 ID.unique() 生成;仅允许 a-z、A-Z、0-9、句点、连字符、下划线,不能以特殊字符开头。最长 36 字符。
contentbodystring是—短信正文。
topicsbodystring[]否—主题 ID 列表。
usersbodystring[]否—用户 ID 列表。
targetsbodystring[]否—目标 ID 列表。
draftbodyboolean否—是否为草稿。
scheduledAtbodystring否可为 null消息排期发送时间(ISO 8601)。必须是未来时间。

输出:201,模型 message(完整字段见前文),关键字段:

字段类型说明
$idstring消息 ID。
$createdAtstring消息创建时间(ISO 8601)。
$updatedAtstring消息更新时间(ISO 8601)。
providerTypestring消息通道类型(email / sms / push)。
topicsstring[]作为收件人的主题 ID 列表。
usersstring[]作为收件人的用户 ID 列表。
targetsstring[]作为收件人的目标 ID 列表。
scheduledAtstring消息计划发送时间。
deliveredAtstring消息实际投递时间。
deliveryErrorsstring[]投递错误列表(如有)。
deliveredTotalinteger已成功投递的收件人数。
dataobject消息数据。
statusstring投递状态。

调用示例:

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": "welcome-email",
  "content": "<h1>欢迎注册</h1>",
  "topics": [
    "announcements"
  ],
  "users": [
    "66b1c2d3e4f5a6b7"
  ],
  "draft": 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"
}

PATCH /v1/messaging/messages/sms/{messageId}

更新短信消息:仅 draft 状态可改。该端点在 spec 中标记为 deprecated(v2.6.0 仍可用,SDK 保留对应方法)。(scope messages.write。SDK:Messages.updateSms。)

输入(application/json)

参数位置类型必填默认/枚举说明
topicsbodystring[]否可为 null主题 ID 列表。
usersbodystring[]否可为 null用户 ID 列表。
targetsbodystring[]否可为 null目标 ID 列表。
contentbodystring否可为 null邮件正文。
draftbodyboolean否可为 null是否为草稿。
scheduledAtbodystring否可为 null消息排期发送时间(ISO 8601)。必须是未来时间。
messageIdpathstring是—消息 ID。

输出:200,模型 message(完整字段见前文),关键字段:

字段类型说明
$idstring消息 ID。
$createdAtstring消息创建时间(ISO 8601)。
$updatedAtstring消息更新时间(ISO 8601)。
providerTypestring消息通道类型(email / sms / push)。
topicsstring[]作为收件人的主题 ID 列表。
usersstring[]作为收件人的用户 ID 列表。
targetsstring[]作为收件人的目标 ID 列表。
scheduledAtstring消息计划发送时间。
deliveredAtstring消息实际投递时间。
deliveryErrorsstring[]投递错误列表(如有)。
deliveredTotalinteger已成功投递的收件人数。
dataobject消息数据。
statusstring投递状态。

调用示例:

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": "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/push

创建一条推送通知:内容字段按 Android / iOS / Web 平台分别生效(scope messages.write。SDK:Messages.createPush。)

输入(application/json)

参数位置类型必填默认/枚举说明
messageIdbodystring是—消息 ID。可自定义,或用 SDK 的 ID.unique() 生成;仅允许 a-z、A-Z、0-9、句点、连字符、下划线,不能以特殊字符开头。最长 36 字符。
titlebodystring否—推送标题。
bodybodystring否—推送正文。
topicsbodystring[]否—主题 ID 列表。
usersbodystring[]否—用户 ID 列表。
targetsbodystring[]否—目标 ID 列表。
databodyobject否可为 null推送附加键值对数据。
actionbodystring否—推送点击动作。
imagebodystring否—推送大图。必须是 Storage 中 jpeg/png/bmp 图片的复合 ID,格式 <BUCKET_ID>:<FILE_ID>。
iconbodystring否—推送图标。仅 Android / Web 生效。
soundbodystring否—推送提示音。仅 Android / iOS 生效。
colorbodystring否—推送颜色。仅 Android 生效。
tagbodystring否—推送标签(折叠同 tag 通知)。仅 Android 生效。
badgebodyinteger否—应用角标数。仅 iOS 生效。
draftbodyboolean否—是否为草稿。
scheduledAtbodystring否可为 null消息排期发送时间(ISO 8601)。必须是未来时间。
contentAvailablebodyboolean否—为 true 时静默后台投递。仅 iOS 生效。
criticalbodyboolean否—为 true 时标记为重要通知,要求应用具备 critical notification entitlement。仅 iOS 生效。
prioritybodystring否normal / high推送优先级。normal 会考虑设备状态、可能延迟投递;high 总是尝试立即投递。
imageInternalbodyboolean否—图片存放在内部默认桶时为 true。

输出:201,模型 message(完整字段见前文),关键字段:

字段类型说明
$idstring消息 ID。
$createdAtstring消息创建时间(ISO 8601)。
$updatedAtstring消息更新时间(ISO 8601)。
providerTypestring消息通道类型(email / sms / push)。
topicsstring[]作为收件人的主题 ID 列表。
usersstring[]作为收件人的用户 ID 列表。
targetsstring[]作为收件人的目标 ID 列表。
scheduledAtstring消息计划发送时间。
deliveredAtstring消息实际投递时间。
deliveryErrorsstring[]投递错误列表(如有)。
deliveredTotalinteger已成功投递的收件人数。
dataobject消息数据。
statusstring投递状态。

调用示例:

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": "welcome-email",
  "topics": [
    "announcements"
  ],
  "data": {
    "orderId": "1024"
  },
  "action": "open-orders",
  "priority": "high",
  "draft": 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"
}

PATCH /v1/messaging/messages/push/{messageId}

更新推送通知:仅 draft 状态可改(scope messages.write。SDK:Messages.updatePush。)

输入(application/json)

参数位置类型必填默认/枚举说明
topicsbodystring[]否可为 null主题 ID 列表。
usersbodystring[]否可为 null用户 ID 列表。
targetsbodystring[]否可为 null目标 ID 列表。
titlebodystring否可为 null推送标题。
bodybodystring否可为 null推送正文。
databodyobject否可为 null推送附加数据。
actionbodystring否可为 null推送点击动作。
imagebodystring否可为 null推送大图。必须是 Storage 中 jpeg/png/bmp 图片的复合 ID,格式 <BUCKET_ID>:<FILE_ID>。
iconbodystring否可为 null推送图标。仅 Android / Web 生效。
soundbodystring否可为 null推送提示音。仅 Android / iOS 生效。
colorbodystring否可为 null推送颜色。仅 Android 生效。
tagbodystring否可为 null推送标签(折叠同 tag 通知)。仅 Android 生效。
badgebodyinteger否可为 null应用角标数。仅 iOS 生效。
draftbodyboolean否可为 null是否为草稿。
scheduledAtbodystring否可为 null消息排期发送时间(ISO 8601)。必须是未来时间。
contentAvailablebodyboolean否可为 null为 true 时静默后台投递。仅 iOS 生效。
criticalbodyboolean否可为 null为 true 时标记为重要通知,要求应用具备 critical notification entitlement。仅 iOS 生效。
prioritybodystring否normal / high;可为 null推送优先级。normal 会考虑设备电量状态、可能延迟发送;high 总是尝试立即投递。
imageInternalbodyboolean否—图片存放在内部默认桶时为 true。
messageIdpathstring是—消息 ID。

输出:200,模型 message(完整字段见前文),关键字段:

字段类型说明
$idstring消息 ID。
$createdAtstring消息创建时间(ISO 8601)。
$updatedAtstring消息更新时间(ISO 8601)。
providerTypestring消息通道类型(email / sms / push)。
topicsstring[]作为收件人的主题 ID 列表。
usersstring[]作为收件人的用户 ID 列表。
targetsstring[]作为收件人的目标 ID 列表。
scheduledAtstring消息计划发送时间。
deliveredAtstring消息实际投递时间。
deliveryErrorsstring[]投递错误列表(如有)。
deliveredTotalinteger已成功投递的收件人数。
dataobject消息数据。
statusstring投递状态。

调用示例:

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

GET /v1/messaging/messages/{messageId}

读取单条消息及其投递状态(status、deliveredTotal、deliveryErrors)(scope messages.read。SDK:Messages.getMessage。)

输入

参数位置类型必填默认/枚举说明
messageIdpathstring是—消息 ID。

输出:200,模型 message(完整字段见前文),关键字段:

字段类型说明
$idstring消息 ID。
$createdAtstring消息创建时间(ISO 8601)。
$updatedAtstring消息更新时间(ISO 8601)。
providerTypestring消息通道类型(email / sms / push)。
topicsstring[]作为收件人的主题 ID 列表。
usersstring[]作为收件人的用户 ID 列表。
targetsstring[]作为收件人的目标 ID 列表。
scheduledAtstring消息计划发送时间。
deliveredAtstring消息实际投递时间。
deliveryErrorsstring[]投递错误列表(如有)。
deliveredTotalinteger已成功投递的收件人数。
dataobject消息数据。
statusstring投递状态。

调用示例:

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。)

输入

参数位置类型必填默认/枚举说明
messageIdpathstring是—消息 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

列出该消息解析出的全部收件目标(由 topics / users / targets 展开得到)(scope messages.read。SDK:Messages.listTargets。)

输入

参数位置类型必填默认/枚举说明
messageIdpathstring是—消息 ID。
queriesquerystring[]否默认 []查询字符串数组,由 SDK 的 Query 构造器生成(形如 limit(25)、equal("name","x"));支持过滤、排序、分页(limit / cursorAfter / cursorBefore);可过滤属性:userId、providerId、identifier、providerType。最多 100 条、每条最长 4096 字符。
totalqueryboolean否默认 true设为 false 时跳过总数计算,返回的 total 固定为 0。

输出:200,模型 targetList:total(匹配总数,total=false 时不计算)+ targets[](当前页数据)。

元素模型 target 关键字段:

字段类型说明
$idstring目标 ID。
$createdAtstring目标创建时间(ISO 8601)。
$updatedAtstring目标更新时间(ISO 8601)。
namestring目标名称。
userIdstring用户 ID。
providerTypestring目标通道类型:email / sms / push。
identifierstring目标标识(邮箱地址 / 手机号 / 推送令牌)。
expiredboolean目标是否已过期。

调用示例:

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": 5,
  "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": "email",
      "identifier": "token",
      "expired": false
    }
  ]
}

GET /v1/messaging/messages/{messageId}/logs

列出该消息的投递日志(仅支持 limit/offset 分页)(scope messages.read。SDK:Logs.listMessageLogs。)

输入

参数位置类型必填默认/枚举说明
messageIdpathstring是—消息 ID。
queriesquerystring[]否默认 []查询字符串数组,由 SDK 的 Query 构造器生成(形如 limit(25)、equal("name","x"));仅支持 limit / offset 两个方法。
totalqueryboolean否默认 true设为 false 时跳过总数计算,返回的 total 固定为 0。

输出:200,模型 logList:total(匹配总数,total=false 时不计算)+ logs[](当前页数据)。

元素模型 log 关键字段:

字段类型说明
eventstring事件名。
userIdstring触发该日志的用户 ID。被代理(impersonation)时记录代理发起者而非被代理用户。
userEmailstring触发该日志的用户邮箱。
modestring事件触发时的 API 模式(admin/key 等)。
ipstring事件发生时的来源 IP。
timestring日志创建时间(ISO 8601)。
clientNamestring客户端名称。
countryNamestring国家/地区名称。

调用示例:

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。)

输入

参数位置类型必填默认/枚举说明
queriesquerystring[]否默认 []查询字符串数组,由 SDK 的 Query 构造器生成(形如 limit(25)、equal("name","x"));支持过滤、排序、分页(limit / cursorAfter / cursorBefore);可过滤属性:name、provider、type、enabled。最多 100 条、每条最长 4096 字符。
searchquerystring否—搜索词,模糊过滤列表结果。最长 256 字符。
totalqueryboolean否默认 true设为 false 时跳过总数计算,返回的 total 固定为 0。

输出:200,模型 providerList:total(匹配总数,total=false 时不计算)+ providers[](当前页数据)。

元素模型 provider 关键字段:

字段类型说明
$idstring提供商 ID。
$createdAtstring提供商创建时间(ISO 8601)。
$updatedAtstring提供商更新时间(ISO 8601)。
namestring提供商实例名称。
providerstring提供商服务标识。
enabledboolean提供商是否启用。
typestring提供商通道类型。
credentialsobject提供商凭证(写入后不回显明文)。
optionsobject提供商选项。

调用示例:

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": "sms",
      "credentials": {
        "key": "123456789"
      },
      "options": {
        "from": "sender-email@mydomain"
      }
    }
  ]
}

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)

参数位置类型必填默认/枚举说明
providerIdbodystring是—提供商 ID。可自定义,或用 SDK 的 ID.unique() 生成;仅允许 a-z、A-Z、0-9、句点、连字符、下划线,不能以特殊字符开头。最长 36 字符。
namebodystring是—提供商名称。
authKeybodystring否—APNS 认证密钥(.p8 私钥内容)。
authKeyIdbodystring否—APNS 密钥 ID。
teamIdbodystring否—APNS 团队 ID。
bundleIdbodystring否—应用 Bundle ID。
sandboxbodyboolean否—是否使用 APNS 沙箱环境。
enabledbodyboolean否可为 null是否启用。

输出:201,模型 provider,字段:

字段类型说明
$idstring提供商 ID。
$createdAtstring提供商创建时间(ISO 8601)。
$updatedAtstring提供商更新时间(ISO 8601)。
namestring提供商实例名称。
providerstring提供商服务标识。
enabledboolean提供商是否启用。
typestring提供商通道类型。
credentialsobject提供商凭证(写入后不回显明文)。
optionsobject提供商选项。

调用示例:

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": "sendgrid-main",
  "name": "主邮件通道",
  "authKey": "-----BEGIN PRIVATE KEY-----\\nMIGT...\\n-----END PRIVATE KEY-----",
  "authKeyId": "ABC123DEFG",
  "teamId": "TEAMID12345",
  "bundleId": "com.example.app",
  "sandbox": false,
  "enabled": true
}'

响应示例:

{
  "$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": "sms",
  "credentials": {
    "key": "123456789"
  },
  "options": {
    "from": "sender-email@mydomain"
  }
}

PATCH /v1/messaging/providers/apns/{providerId}

更新 APNS 提供商:未提供的字段保留现值。该端点在 spec 中标记为 deprecated(v2.6.0 仍可用,SDK 保留对应方法)。(scope providers.write。SDK:Providers.updateApnsProvider。)

输入(application/json)

参数位置类型必填默认/枚举说明
namebodystring否—提供商名称。
enabledbodyboolean否可为 null是否启用。
authKeybodystring否—APNS 认证密钥(.p8 私钥内容)。
authKeyIdbodystring否—APNS 密钥 ID。
teamIdbodystring否—APNS 团队 ID。
bundleIdbodystring否—应用 Bundle ID。
sandboxbodyboolean否可为 null是否使用 APNS 沙箱环境。
providerIdpathstring是—提供商 ID。

输出:200,模型 provider(完整字段见前文),关键字段:

字段类型说明
$idstring提供商 ID。
$createdAtstring提供商创建时间(ISO 8601)。
$updatedAtstring提供商更新时间(ISO 8601)。
namestring提供商实例名称。
providerstring提供商服务标识。
enabledboolean提供商是否启用。
typestring提供商通道类型。
credentialsobject提供商凭证(写入后不回显明文)。
optionsobject提供商选项。

调用示例:

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": "主邮件通道",
  "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": "Mailgun",
  "provider": "mailgun",
  "enabled": true,
  "type": "sms",
  "credentials": {
    "key": "123456789"
  },
  "options": {
    "from": "sender-email@mydomain"
  }
}

POST /v1/messaging/providers/fcm

创建 Firebase Cloud Messaging(FCM)提供商:提交服务账号 JSON。该端点在 spec 中标记为 deprecated(v2.6.0 仍可用,SDK 保留对应方法)。(scope providers.write。SDK:Providers.createFcmProvider。)

输入(application/json)

参数位置类型必填默认/枚举说明
providerIdbodystring是—提供商 ID。可自定义,或用 SDK 的 ID.unique() 生成;仅允许 a-z、A-Z、0-9、句点、连字符、下划线,不能以特殊字符开头。最长 36 字符。
namebodystring是—提供商名称。
serviceAccountJSONbodyobject否可为 nullFCM 服务账号 JSON。
enabledbodyboolean否可为 null是否启用。

输出:201,模型 provider(完整字段见前文),关键字段:

字段类型说明
$idstring提供商 ID。
$createdAtstring提供商创建时间(ISO 8601)。
$updatedAtstring提供商更新时间(ISO 8601)。
namestring提供商实例名称。
providerstring提供商服务标识。
enabledboolean提供商是否启用。
typestring提供商通道类型。
credentialsobject提供商凭证(写入后不回显明文)。
optionsobject提供商选项。

调用示例:

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": "sendgrid-main",
  "name": "主邮件通道",
  "serviceAccountJSON": {
    "type": "service_account",
    "project_id": "my-project"
  },
  "enabled": true
}'

响应示例:

{
  "$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": "sms",
  "credentials": {
    "key": "123456789"
  },
  "options": {
    "from": "sender-email@mydomain"
  }
}

PATCH /v1/messaging/providers/fcm/{providerId}

更新 FCM 提供商。该端点在 spec 中标记为 deprecated(v2.6.0 仍可用,SDK 保留对应方法)。(scope providers.write。SDK:Providers.updateFcmProvider。)

输入(application/json)

参数位置类型必填默认/枚举说明
namebodystring否—提供商名称。
enabledbodyboolean否可为 null是否启用。
serviceAccountJSONbodyobject否可为 nullFCM 服务账号 JSON。
providerIdpathstring是—提供商 ID。

输出:200,模型 provider(完整字段见前文),关键字段:

字段类型说明
$idstring提供商 ID。
$createdAtstring提供商创建时间(ISO 8601)。
$updatedAtstring提供商更新时间(ISO 8601)。
namestring提供商实例名称。
providerstring提供商服务标识。
enabledboolean提供商是否启用。
typestring提供商通道类型。
credentialsobject提供商凭证(写入后不回显明文)。
optionsobject提供商选项。

调用示例:

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": "主邮件通道",
  "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": "Mailgun",
  "provider": "mailgun",
  "enabled": true,
  "type": "sms",
  "credentials": {
    "key": "123456789"
  },
  "options": {
    "from": "sender-email@mydomain"
  }
}

POST /v1/messaging/providers/mailgun

创建 Mailgun 邮件提供商(scope providers.write。SDK:Providers.createMailgunProvider。)

输入(application/json)

参数位置类型必填默认/枚举说明
providerIdbodystring是—提供商 ID。可自定义,或用 SDK 的 ID.unique() 生成;仅允许 a-z、A-Z、0-9、句点、连字符、下划线,不能以特殊字符开头。最长 36 字符。
namebodystring是—提供商名称。
apiKeybodystring否—Mailgun API Key。
domainbodystring否—Mailgun 域名。
isEuRegionbodyboolean否可为 null是否使用 Mailgun 欧盟区域。
fromNamebodystring否—发件人名称。
fromEmailbodystring否—发件人邮箱。
replyToNamebodystring否—邮件 Reply-To 名称。默认取发件人名称;须与 Reply-To 邮箱同时提供。
replyToEmailbodystring否—邮件 Reply-To 邮箱。默认取发件人邮箱;须与 Reply-To 名称同时提供。
enabledbodyboolean否可为 null是否启用。

输出:201,模型 provider(完整字段见前文),关键字段:

字段类型说明
$idstring提供商 ID。
$createdAtstring提供商创建时间(ISO 8601)。
$updatedAtstring提供商更新时间(ISO 8601)。
namestring提供商实例名称。
providerstring提供商服务标识。
enabledboolean提供商是否启用。
typestring提供商通道类型。
credentialsobject提供商凭证(写入后不回显明文)。
optionsobject提供商选项。

调用示例:

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": "sendgrid-main",
  "name": "主邮件通道",
  "apiKey": "key-1234567890abcdef",
  "domain": "mg.example.com",
  "isEuRegion": false,
  "fromName": "AppBase",
  "fromEmail": "noreply@example.com",
  "replyToName": "支持团队",
  "replyToEmail": "support@example.com",
  "enabled": true
}'

响应示例:

{
  "$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": "sms",
  "credentials": {
    "key": "123456789"
  },
  "options": {
    "from": "sender-email@mydomain"
  }
}

PATCH /v1/messaging/providers/mailgun/{providerId}

更新 Mailgun 提供商(scope providers.write。SDK:Providers.updateMailgunProvider。)

输入(application/json)

参数位置类型必填默认/枚举说明
namebodystring否—提供商名称。
apiKeybodystring否—Mailgun API Key。
domainbodystring否—Mailgun 域名。
isEuRegionbodyboolean否可为 null是否使用 Mailgun 欧盟区域。
enabledbodyboolean否可为 null是否启用。
fromNamebodystring否—发件人名称。
fromEmailbodystring否—发件人邮箱。
replyToNamebodystring否—邮件 Reply-To 名称。默认取发件人名称。
replyToEmailbodystring否—邮件 Reply-To 邮箱。默认取发件人邮箱。
providerIdpathstring是—提供商 ID。

输出:200,模型 provider(完整字段见前文),关键字段:

字段类型说明
$idstring提供商 ID。
$createdAtstring提供商创建时间(ISO 8601)。
$updatedAtstring提供商更新时间(ISO 8601)。
namestring提供商实例名称。
providerstring提供商服务标识。
enabledboolean提供商是否启用。
typestring提供商通道类型。
credentialsobject提供商凭证(写入后不回显明文)。
optionsobject提供商选项。

调用示例:

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": "主邮件通道",
  "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": "sms",
  "credentials": {
    "key": "123456789"
  },
  "options": {
    "from": "sender-email@mydomain"
  }
}

POST /v1/messaging/providers/msg91

创建 MSG91 短信提供商(scope providers.write。SDK:Providers.createMsg91Provider。)

输入(application/json)

参数位置类型必填默认/枚举说明
providerIdbodystring是—提供商 ID。可自定义,或用 SDK 的 ID.unique() 生成;仅允许 a-z、A-Z、0-9、句点、连字符、下划线,不能以特殊字符开头。最长 36 字符。
namebodystring是—提供商名称。
templateIdbodystring否—MSG91 模板 ID。
senderIdbodystring否—MSG91 发件人 ID。
authKeybodystring否—MSG91 认证密钥。
enabledbodyboolean否可为 null是否启用。

输出:201,模型 provider(完整字段见前文),关键字段:

字段类型说明
$idstring提供商 ID。
$createdAtstring提供商创建时间(ISO 8601)。
$updatedAtstring提供商更新时间(ISO 8601)。
namestring提供商实例名称。
providerstring提供商服务标识。
enabledboolean提供商是否启用。
typestring提供商通道类型。
credentialsobject提供商凭证(写入后不回显明文)。
optionsobject提供商选项。

调用示例:

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": "sendgrid-main",
  "name": "主邮件通道",
  "templateId": "6789abcdef012345",
  "senderId": "APPBASE",
  "authKey": "-----BEGIN PRIVATE KEY-----\\nMIGT...\\n-----END PRIVATE KEY-----",
  "enabled": true
}'

响应示例:

{
  "$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": "sms",
  "credentials": {
    "key": "123456789"
  },
  "options": {
    "from": "sender-email@mydomain"
  }
}

PATCH /v1/messaging/providers/msg91/{providerId}

更新 MSG91 提供商(scope providers.write。SDK:Providers.updateMsg91Provider。)

输入(application/json)

参数位置类型必填默认/枚举说明
namebodystring否—提供商名称。
enabledbodyboolean否可为 null是否启用。
templateIdbodystring否—MSG91 模板 ID。
senderIdbodystring否—MSG91 发件人 ID。
authKeybodystring否—MSG91 认证密钥。
providerIdpathstring是—提供商 ID。

输出:200,模型 provider(完整字段见前文),关键字段:

字段类型说明
$idstring提供商 ID。
$createdAtstring提供商创建时间(ISO 8601)。
$updatedAtstring提供商更新时间(ISO 8601)。
namestring提供商实例名称。
providerstring提供商服务标识。
enabledboolean提供商是否启用。
typestring提供商通道类型。
credentialsobject提供商凭证(写入后不回显明文)。
optionsobject提供商选项。

调用示例:

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": "主邮件通道",
  "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": "Mailgun",
  "provider": "mailgun",
  "enabled": true,
  "type": "sms",
  "credentials": {
    "key": "123456789"
  },
  "options": {
    "from": "sender-email@mydomain"
  }
}

POST /v1/messaging/providers/resend

创建 Resend 邮件提供商(scope providers.write。SDK:Providers.createResendProvider。)

输入(application/json)

参数位置类型必填默认/枚举说明
providerIdbodystring是—提供商 ID。可自定义,或用 SDK 的 ID.unique() 生成;仅允许 a-z、A-Z、0-9、句点、连字符、下划线,不能以特殊字符开头。最长 36 字符。
namebodystring是—提供商名称。
apiKeybodystring否—Resend API Key。
fromNamebodystring否—发件人名称。
fromEmailbodystring否—发件人邮箱。
replyToNamebodystring否—邮件 Reply-To 名称。默认取发件人名称。
replyToEmailbodystring否—邮件 Reply-To 邮箱。默认取发件人邮箱。
enabledbodyboolean否可为 null是否启用。

输出:201,模型 provider(完整字段见前文),关键字段:

字段类型说明
$idstring提供商 ID。
$createdAtstring提供商创建时间(ISO 8601)。
$updatedAtstring提供商更新时间(ISO 8601)。
namestring提供商实例名称。
providerstring提供商服务标识。
enabledboolean提供商是否启用。
typestring提供商通道类型。
credentialsobject提供商凭证(写入后不回显明文)。
optionsobject提供商选项。

调用示例:

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": "sendgrid-main",
  "name": "主邮件通道",
  "apiKey": "key-1234567890abcdef",
  "fromName": "AppBase",
  "fromEmail": "noreply@example.com",
  "replyToName": "支持团队",
  "replyToEmail": "support@example.com",
  "enabled": true
}'

响应示例:

{
  "$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": "sms",
  "credentials": {
    "key": "123456789"
  },
  "options": {
    "from": "sender-email@mydomain"
  }
}

PATCH /v1/messaging/providers/resend/{providerId}

更新 Resend 提供商(scope providers.write。SDK:Providers.updateResendProvider。)

输入(application/json)

参数位置类型必填默认/枚举说明
namebodystring否—提供商名称。
enabledbodyboolean否可为 null是否启用。
apiKeybodystring否—Resend API Key。
fromNamebodystring否—发件人名称。
fromEmailbodystring否—发件人邮箱。
replyToNamebodystring否—邮件 Reply-To 名称。默认取发件人名称。
replyToEmailbodystring否—邮件 Reply-To 邮箱。默认取发件人邮箱。
providerIdpathstring是—提供商 ID。

输出:200,模型 provider(完整字段见前文),关键字段:

字段类型说明
$idstring提供商 ID。
$createdAtstring提供商创建时间(ISO 8601)。
$updatedAtstring提供商更新时间(ISO 8601)。
namestring提供商实例名称。
providerstring提供商服务标识。
enabledboolean提供商是否启用。
typestring提供商通道类型。
credentialsobject提供商凭证(写入后不回显明文)。
optionsobject提供商选项。

调用示例:

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": "主邮件通道",
  "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": "Mailgun",
  "provider": "mailgun",
  "enabled": true,
  "type": "sms",
  "credentials": {
    "key": "123456789"
  },
  "options": {
    "from": "sender-email@mydomain"
  }
}

POST /v1/messaging/providers/sendgrid

创建 SendGrid 邮件提供商(scope providers.write。SDK:Providers.createSendgridProvider。)

输入(application/json)

参数位置类型必填默认/枚举说明
providerIdbodystring是—提供商 ID。可自定义,或用 SDK 的 ID.unique() 生成;仅允许 a-z、A-Z、0-9、句点、连字符、下划线,不能以特殊字符开头。最长 36 字符。
namebodystring是—提供商名称。
apiKeybodystring否—SendGrid API Key。
fromNamebodystring否—发件人名称。
fromEmailbodystring否—发件人邮箱。
replyToNamebodystring否—邮件 Reply-To 名称。默认取发件人名称。
replyToEmailbodystring否—邮件 Reply-To 邮箱。默认取发件人邮箱。
enabledbodyboolean否可为 null是否启用。

输出:201,模型 provider(完整字段见前文),关键字段:

字段类型说明
$idstring提供商 ID。
$createdAtstring提供商创建时间(ISO 8601)。
$updatedAtstring提供商更新时间(ISO 8601)。
namestring提供商实例名称。
providerstring提供商服务标识。
enabledboolean提供商是否启用。
typestring提供商通道类型。
credentialsobject提供商凭证(写入后不回显明文)。
optionsobject提供商选项。

调用示例:

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": "主邮件通道",
  "apiKey": "key-1234567890abcdef",
  "fromName": "AppBase",
  "fromEmail": "noreply@example.com",
  "replyToName": "支持团队",
  "replyToEmail": "support@example.com",
  "enabled": true
}'

响应示例:

{
  "$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": "sms",
  "credentials": {
    "key": "123456789"
  },
  "options": {
    "from": "sender-email@mydomain"
  }
}

PATCH /v1/messaging/providers/sendgrid/{providerId}

更新 SendGrid 提供商(scope providers.write。SDK:Providers.updateSendgridProvider。)

输入(application/json)

参数位置类型必填默认/枚举说明
namebodystring否—提供商名称。
enabledbodyboolean否可为 null是否启用。
apiKeybodystring否—SendGrid API Key。
fromNamebodystring否—发件人名称。
fromEmailbodystring否—发件人邮箱。
replyToNamebodystring否—邮件 Reply-To 名称。默认取发件人名称。
replyToEmailbodystring否—邮件 Reply-To 邮箱。默认取发件人邮箱。
providerIdpathstring是—提供商 ID。

输出:200,模型 provider(完整字段见前文),关键字段:

字段类型说明
$idstring提供商 ID。
$createdAtstring提供商创建时间(ISO 8601)。
$updatedAtstring提供商更新时间(ISO 8601)。
namestring提供商实例名称。
providerstring提供商服务标识。
enabledboolean提供商是否启用。
typestring提供商通道类型。
credentialsobject提供商凭证(写入后不回显明文)。
optionsobject提供商选项。

调用示例:

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": "主邮件通道",
  "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": "Mailgun",
  "provider": "mailgun",
  "enabled": true,
  "type": "sms",
  "credentials": {
    "key": "123456789"
  },
  "options": {
    "from": "sender-email@mydomain"
  }
}

POST /v1/messaging/providers/smtp

创建通用 SMTP 邮件提供商:主机、端口、加密方式与认证凭证。该端点在 spec 中标记为 deprecated(v2.6.0 仍可用,SDK 保留对应方法)。(scope providers.write。SDK:Providers.createSmtpProvider。)

输入(application/json)

参数位置类型必填默认/枚举说明
providerIdbodystring是—提供商 ID。可自定义,或用 SDK 的 ID.unique() 生成;仅允许 a-z、A-Z、0-9、句点、连字符、下划线,不能以特殊字符开头。最长 36 字符。
namebodystring是—提供商名称。
hostbodystring是—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.
portbodyinteger否—SMTP 端口。
usernamebodystring否—认证用户名。
passwordbodystring否—认证密码。
encryptionbodystring否none / ssl / tls加密方式:none(不加密)/ ssl / tls。
autoTLSbodyboolean否—是否启用 SMTP AutoTLS。
mailerbodystring否—X-Mailer 请求头的值。
fromNamebodystring否—发件人名称。
fromEmailbodystring否—发件人邮箱。
replyToNamebodystring否—邮件 Reply-To 名称。默认取发件人名称。
replyToEmailbodystring否—邮件 Reply-To 邮箱。默认取发件人邮箱。
enabledbodyboolean否可为 null是否启用。

输出:201,模型 provider(完整字段见前文),关键字段:

字段类型说明
$idstring提供商 ID。
$createdAtstring提供商创建时间(ISO 8601)。
$updatedAtstring提供商更新时间(ISO 8601)。
namestring提供商实例名称。
providerstring提供商服务标识。
enabledboolean提供商是否启用。
typestring提供商通道类型。
credentialsobject提供商凭证(写入后不回显明文)。
optionsobject提供商选项。

调用示例:

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": "sendgrid-main",
  "name": "主邮件通道",
  "host": "smtp.example.com",
  "port": 587,
  "username": "postmaster@example.com",
  "password": "smtp-password",
  "encryption": "none",
  "autoTLS": true,
  "mailer": "AppBase",
  "fromName": "AppBase"
}'

响应示例:

{
  "$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": "sms",
  "credentials": {
    "key": "123456789"
  },
  "options": {
    "from": "sender-email@mydomain"
  }
}

PATCH /v1/messaging/providers/smtp/{providerId}

更新 SMTP 提供商。该端点在 spec 中标记为 deprecated(v2.6.0 仍可用,SDK 保留对应方法)。(scope providers.write。SDK:Providers.updateSmtpProvider。)

输入(application/json)

参数位置类型必填默认/枚举说明
namebodystring否—提供商名称。
hostbodystring否—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.
portbodyinteger否可为 nullSMTP 端口。
usernamebodystring否—认证用户名。
passwordbodystring否—认证密码。
encryptionbodystring否none / ssl / tls加密方式:ssl / tls。
autoTLSbodyboolean否可为 null是否启用 SMTP AutoTLS。
mailerbodystring否—X-Mailer 请求头的值。
fromNamebodystring否—发件人名称。
fromEmailbodystring否—发件人邮箱。
replyToNamebodystring否—邮件 Reply-To 名称。默认取发件人名称。
replyToEmailbodystring否—邮件 Reply-To 邮箱。默认取发件人邮箱。
enabledbodyboolean否可为 null是否启用。
providerIdpathstring是—提供商 ID。

输出:200,模型 provider(完整字段见前文),关键字段:

字段类型说明
$idstring提供商 ID。
$createdAtstring提供商创建时间(ISO 8601)。
$updatedAtstring提供商更新时间(ISO 8601)。
namestring提供商实例名称。
providerstring提供商服务标识。
enabledboolean提供商是否启用。
typestring提供商通道类型。
credentialsobject提供商凭证(写入后不回显明文)。
optionsobject提供商选项。

调用示例:

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": "主邮件通道",
  "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": "Mailgun",
  "provider": "mailgun",
  "enabled": true,
  "type": "sms",
  "credentials": {
    "key": "123456789"
  },
  "options": {
    "from": "sender-email@mydomain"
  }
}

POST /v1/messaging/providers/telesign

创建 Telesign 短信提供商(scope providers.write。SDK:Providers.createTelesignProvider。)

输入(application/json)

参数位置类型必填默认/枚举说明
providerIdbodystring是—提供商 ID。可自定义,或用 SDK 的 ID.unique() 生成;仅允许 a-z、A-Z、0-9、句点、连字符、下划线,不能以特殊字符开头。最长 36 字符。
namebodystring是—提供商名称。
frombodystring否—发件人手机号,须带国家码的 + 前缀,如 +16175551212。
customerIdbodystring否—Telesign 客户 ID。
apiKeybodystring否—Telesign API Key。
enabledbodyboolean否可为 null是否启用。

输出:201,模型 provider(完整字段见前文),关键字段:

字段类型说明
$idstring提供商 ID。
$createdAtstring提供商创建时间(ISO 8601)。
$updatedAtstring提供商更新时间(ISO 8601)。
namestring提供商实例名称。
providerstring提供商服务标识。
enabledboolean提供商是否启用。
typestring提供商通道类型。
credentialsobject提供商凭证(写入后不回显明文)。
optionsobject提供商选项。

调用示例:

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": "sendgrid-main",
  "name": "主邮件通道",
  "from": "+16175551212",
  "customerId": "FFFFFFFF-1111-2222-3333-444444444444",
  "apiKey": "key-1234567890abcdef",
  "enabled": true
}'

响应示例:

{
  "$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": "sms",
  "credentials": {
    "key": "123456789"
  },
  "options": {
    "from": "sender-email@mydomain"
  }
}

PATCH /v1/messaging/providers/telesign/{providerId}

更新 Telesign 提供商(scope providers.write。SDK:Providers.updateTelesignProvider。)

输入(application/json)

参数位置类型必填默认/枚举说明
namebodystring否—提供商名称。
enabledbodyboolean否可为 null是否启用。
customerIdbodystring否—Telesign 客户 ID。
apiKeybodystring否—Telesign API Key。
frombodystring否—发信号码。
providerIdpathstring是—提供商 ID。

输出:200,模型 provider(完整字段见前文),关键字段:

字段类型说明
$idstring提供商 ID。
$createdAtstring提供商创建时间(ISO 8601)。
$updatedAtstring提供商更新时间(ISO 8601)。
namestring提供商实例名称。
providerstring提供商服务标识。
enabledboolean提供商是否启用。
typestring提供商通道类型。
credentialsobject提供商凭证(写入后不回显明文)。
optionsobject提供商选项。

调用示例:

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": "主邮件通道",
  "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": "Mailgun",
  "provider": "mailgun",
  "enabled": true,
  "type": "sms",
  "credentials": {
    "key": "123456789"
  },
  "options": {
    "from": "sender-email@mydomain"
  }
}

POST /v1/messaging/providers/textmagic

创建 Textmagic 短信提供商(scope providers.write。SDK:Providers.createTextmagicProvider。)

输入(application/json)

参数位置类型必填默认/枚举说明
providerIdbodystring是—提供商 ID。可自定义,或用 SDK 的 ID.unique() 生成;仅允许 a-z、A-Z、0-9、句点、连字符、下划线,不能以特殊字符开头。最长 36 字符。
namebodystring是—提供商名称。
frombodystring否—发件人手机号,须带国家码的 + 前缀,如 +16175551212。
usernamebodystring否—Textmagic 用户名。
apiKeybodystring否—Textmagic API Key。
enabledbodyboolean否可为 null是否启用。

输出:201,模型 provider(完整字段见前文),关键字段:

字段类型说明
$idstring提供商 ID。
$createdAtstring提供商创建时间(ISO 8601)。
$updatedAtstring提供商更新时间(ISO 8601)。
namestring提供商实例名称。
providerstring提供商服务标识。
enabledboolean提供商是否启用。
typestring提供商通道类型。
credentialsobject提供商凭证(写入后不回显明文)。
optionsobject提供商选项。

调用示例:

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": "sendgrid-main",
  "name": "主邮件通道",
  "from": "+16175551212",
  "username": "postmaster@example.com",
  "apiKey": "key-1234567890abcdef",
  "enabled": true
}'

响应示例:

{
  "$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": "sms",
  "credentials": {
    "key": "123456789"
  },
  "options": {
    "from": "sender-email@mydomain"
  }
}

PATCH /v1/messaging/providers/textmagic/{providerId}

更新 Textmagic 提供商(scope providers.write。SDK:Providers.updateTextmagicProvider。)

输入(application/json)

参数位置类型必填默认/枚举说明
namebodystring否—提供商名称。
enabledbodyboolean否可为 null是否启用。
usernamebodystring否—Textmagic 用户名。
apiKeybodystring否—Textmagic API Key。
frombodystring否—发信号码。
providerIdpathstring是—提供商 ID。

输出:200,模型 provider(完整字段见前文),关键字段:

字段类型说明
$idstring提供商 ID。
$createdAtstring提供商创建时间(ISO 8601)。
$updatedAtstring提供商更新时间(ISO 8601)。
namestring提供商实例名称。
providerstring提供商服务标识。
enabledboolean提供商是否启用。
typestring提供商通道类型。
credentialsobject提供商凭证(写入后不回显明文)。
optionsobject提供商选项。

调用示例:

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": "主邮件通道",
  "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": "Mailgun",
  "provider": "mailgun",
  "enabled": true,
  "type": "sms",
  "credentials": {
    "key": "123456789"
  },
  "options": {
    "from": "sender-email@mydomain"
  }
}

POST /v1/messaging/providers/twilio

创建 Twilio 短信提供商(scope providers.write。SDK:Providers.createTwilioProvider。)

输入(application/json)

参数位置类型必填默认/枚举说明
providerIdbodystring是—提供商 ID。可自定义,或用 SDK 的 ID.unique() 生成;仅允许 a-z、A-Z、0-9、句点、连字符、下划线,不能以特殊字符开头。最长 36 字符。
namebodystring是—提供商名称。
frombodystring否—发件人手机号,须带国家码的 + 前缀,如 +16175551212。
accountSidbodystring否—Twilio Account SID。
authTokenbodystring否—Twilio Auth Token。
enabledbodyboolean否可为 null是否启用。

输出:201,模型 provider(完整字段见前文),关键字段:

字段类型说明
$idstring提供商 ID。
$createdAtstring提供商创建时间(ISO 8601)。
$updatedAtstring提供商更新时间(ISO 8601)。
namestring提供商实例名称。
providerstring提供商服务标识。
enabledboolean提供商是否启用。
typestring提供商通道类型。
credentialsobject提供商凭证(写入后不回显明文)。
optionsobject提供商选项。

调用示例:

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": "sendgrid-main",
  "name": "主邮件通道",
  "from": "+16175551212",
  "accountSid": "ACb1c2d3e4f5a6b7c8d9e0f1a2b3c4d5e6f",
  "authToken": "authtoken1234567890abcdef",
  "enabled": true
}'

响应示例:

{
  "$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": "sms",
  "credentials": {
    "key": "123456789"
  },
  "options": {
    "from": "sender-email@mydomain"
  }
}

PATCH /v1/messaging/providers/twilio/{providerId}

更新 Twilio 提供商(scope providers.write。SDK:Providers.updateTwilioProvider。)

输入(application/json)

参数位置类型必填默认/枚举说明
namebodystring否—提供商名称。
enabledbodyboolean否可为 null是否启用。
accountSidbodystring否—Twilio Account SID。
authTokenbodystring否—Twilio Auth Token。
frombodystring否—发信号码。
providerIdpathstring是—提供商 ID。

输出:200,模型 provider(完整字段见前文),关键字段:

字段类型说明
$idstring提供商 ID。
$createdAtstring提供商创建时间(ISO 8601)。
$updatedAtstring提供商更新时间(ISO 8601)。
namestring提供商实例名称。
providerstring提供商服务标识。
enabledboolean提供商是否启用。
typestring提供商通道类型。
credentialsobject提供商凭证(写入后不回显明文)。
optionsobject提供商选项。

调用示例:

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": "主邮件通道",
  "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": "Mailgun",
  "provider": "mailgun",
  "enabled": true,
  "type": "sms",
  "credentials": {
    "key": "123456789"
  },
  "options": {
    "from": "sender-email@mydomain"
  }
}

POST /v1/messaging/providers/vonage

创建 Vonage 短信提供商(scope providers.write。SDK:Providers.createVonageProvider。)

输入(application/json)

参数位置类型必填默认/枚举说明
providerIdbodystring是—提供商 ID。可自定义,或用 SDK 的 ID.unique() 生成;仅允许 a-z、A-Z、0-9、句点、连字符、下划线,不能以特殊字符开头。最长 36 字符。
namebodystring是—提供商名称。
frombodystring否—发件人手机号,须带国家码的 + 前缀,如 +16175551212。
apiKeybodystring否—Vonage API Key。
apiSecretbodystring否—Vonage API Secret。
enabledbodyboolean否可为 null是否启用。

输出:201,模型 provider(完整字段见前文),关键字段:

字段类型说明
$idstring提供商 ID。
$createdAtstring提供商创建时间(ISO 8601)。
$updatedAtstring提供商更新时间(ISO 8601)。
namestring提供商实例名称。
providerstring提供商服务标识。
enabledboolean提供商是否启用。
typestring提供商通道类型。
credentialsobject提供商凭证(写入后不回显明文)。
optionsobject提供商选项。

调用示例:

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": "sendgrid-main",
  "name": "主邮件通道",
  "from": "+16175551212",
  "apiKey": "key-1234567890abcdef",
  "apiSecret": "apisecret1234567890abcdef",
  "enabled": true
}'

响应示例:

{
  "$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": "sms",
  "credentials": {
    "key": "123456789"
  },
  "options": {
    "from": "sender-email@mydomain"
  }
}

PATCH /v1/messaging/providers/vonage/{providerId}

更新 Vonage 提供商(scope providers.write。SDK:Providers.updateVonageProvider。)

输入(application/json)

参数位置类型必填默认/枚举说明
namebodystring否—提供商名称。
enabledbodyboolean否可为 null是否启用。
apiKeybodystring否—Vonage API Key。
apiSecretbodystring否—Vonage API Secret。
frombodystring否—发信号码。
providerIdpathstring是—提供商 ID。

输出:200,模型 provider(完整字段见前文),关键字段:

字段类型说明
$idstring提供商 ID。
$createdAtstring提供商创建时间(ISO 8601)。
$updatedAtstring提供商更新时间(ISO 8601)。
namestring提供商实例名称。
providerstring提供商服务标识。
enabledboolean提供商是否启用。
typestring提供商通道类型。
credentialsobject提供商凭证(写入后不回显明文)。
optionsobject提供商选项。

调用示例:

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": "主邮件通道",
  "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": "Mailgun",
  "provider": "mailgun",
  "enabled": true,
  "type": "sms",
  "credentials": {
    "key": "123456789"
  },
  "options": {
    "from": "sender-email@mydomain"
  }
}

GET /v1/messaging/providers/{providerId}

按 ID 读取提供商详情(凭证不回显明文)(scope providers.read。SDK:Providers.getProvider。)

输入

参数位置类型必填默认/枚举说明
providerIdpathstring是—提供商 ID。

输出:200,模型 provider(完整字段见前文),关键字段:

字段类型说明
$idstring提供商 ID。
$createdAtstring提供商创建时间(ISO 8601)。
$updatedAtstring提供商更新时间(ISO 8601)。
namestring提供商实例名称。
providerstring提供商服务标识。
enabledboolean提供商是否启用。
typestring提供商通道类型。
credentialsobject提供商凭证(写入后不回显明文)。
optionsobject提供商选项。

调用示例:

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": "sms",
  "credentials": {
    "key": "123456789"
  },
  "options": {
    "from": "sender-email@mydomain"
  }
}

DELETE /v1/messaging/providers/{providerId}

删除提供商:未发送消息会因缺少可用提供商而投递失败(scope providers.write。SDK:Providers.deleteProvider。)

输入

参数位置类型必填默认/枚举说明
providerIdpathstring是—提供商 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。)

输入

参数位置类型必填默认/枚举说明
providerIdpathstring是—提供商 ID。
queriesquerystring[]否默认 []查询字符串数组,由 SDK 的 Query 构造器生成(形如 limit(25)、equal("name","x"));仅支持 limit / offset 两个方法。
totalqueryboolean否默认 true设为 false 时跳过总数计算,返回的 total 固定为 0。

输出:200,模型 logList:total(匹配总数,total=false 时不计算)+ logs[](当前页数据)。

元素模型 log 关键字段:

字段类型说明
eventstring事件名。
userIdstring触发该日志的用户 ID。被代理(impersonation)时记录代理发起者而非被代理用户。
userEmailstring触发该日志的用户邮箱。
modestring事件触发时的 API 模式(admin/key 等)。
ipstring事件发生时的来源 IP。
timestring日志创建时间(ISO 8601)。
clientNamestring客户端名称。
countryNamestring国家/地区名称。

调用示例:

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。)

输入

参数位置类型必填默认/枚举说明
queriesquerystring[]否默认 []查询字符串数组,由 SDK 的 Query 构造器生成(形如 limit(25)、equal("name","x"));支持过滤、排序、分页(limit / cursorAfter / cursorBefore);可过滤属性:name、description、emailTotal、smsTotal、pushTotal。最多 100 条、每条最长 4096 字符。
searchquerystring否—搜索词,模糊过滤列表结果。最长 256 字符。
totalqueryboolean否默认 true设为 false 时跳过总数计算,返回的 total 固定为 0。

输出:200,模型 topicList:total(匹配总数,total=false 时不计算)+ topics[](当前页数据)。

元素模型 topic 关键字段:

字段类型说明
$idstring主题 ID。
$createdAtstring主题创建时间(ISO 8601)。
$updatedAtstring主题更新时间(ISO 8601)。
namestring主题名称。
emailTotalinteger订阅该主题的邮件目标数。
smsTotalinteger订阅该主题的短信目标数。
pushTotalinteger订阅该主题的推送目标数。
subscribestring[]可订阅角色。

调用示例:

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)

参数位置类型必填默认/枚举说明
topicIdbodystring是—主题 ID。可自定义新 ID。
namebodystring是—主题名称。
subscribebodystring[]否—拥有订阅权限的角色数组。默认所有用户都可订阅。最多 100 个角色,每个最长 64 字符。

输出:201,模型 topic,字段:

字段类型说明
$idstring主题 ID。
$createdAtstring主题创建时间(ISO 8601)。
$updatedAtstring主题更新时间(ISO 8601)。
namestring主题名称。
emailTotalinteger订阅该主题的邮件目标数。
smsTotalinteger订阅该主题的短信目标数。
pushTotalinteger订阅该主题的推送目标数。
subscribestring[]可订阅角色。

调用示例:

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。)

输入

参数位置类型必填默认/枚举说明
topicIdpathstring是—主题 ID。

输出:200,模型 topic(完整字段见前文),关键字段:

字段类型说明
$idstring主题 ID。
$createdAtstring主题创建时间(ISO 8601)。
$updatedAtstring主题更新时间(ISO 8601)。
namestring主题名称。
emailTotalinteger订阅该主题的邮件目标数。
smsTotalinteger订阅该主题的短信目标数。
pushTotalinteger订阅该主题的推送目标数。
subscribestring[]可订阅角色。

调用示例:

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)

参数位置类型必填默认/枚举说明
namebodystring否可为 null主题名称。
subscribebodystring[]否可为 null拥有订阅权限的角色数组。默认所有用户都可订阅。最多 100 个角色,每个最长 64 字符。
topicIdpathstring是—主题 ID。

输出:200,模型 topic(完整字段见前文),关键字段:

字段类型说明
$idstring主题 ID。
$createdAtstring主题创建时间(ISO 8601)。
$updatedAtstring主题更新时间(ISO 8601)。
namestring主题名称。
emailTotalinteger订阅该主题的邮件目标数。
smsTotalinteger订阅该主题的短信目标数。
pushTotalinteger订阅该主题的推送目标数。
subscribestring[]可订阅角色。

调用示例:

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。)

输入

参数位置类型必填默认/枚举说明
topicIdpathstring是—主题 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。)

输入

参数位置类型必填默认/枚举说明
topicIdpathstring是—主题 ID。
queriesquerystring[]否默认 []查询字符串数组,由 SDK 的 Query 构造器生成(形如 limit(25)、equal("name","x"));仅支持 limit / offset 两个方法。
totalqueryboolean否默认 true设为 false 时跳过总数计算,返回的 total 固定为 0。

输出:200,模型 logList:total(匹配总数,total=false 时不计算)+ logs[](当前页数据)。

元素模型 log 关键字段:

字段类型说明
eventstring事件名。
userIdstring触发该日志的用户 ID。被代理(impersonation)时记录代理发起者而非被代理用户。
userEmailstring触发该日志的用户邮箱。
modestring事件触发时的 API 模式(admin/key 等)。
ipstring事件发生时的来源 IP。
timestring日志创建时间(ISO 8601)。
clientNamestring客户端名称。
countryNamestring国家/地区名称。

调用示例:

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。)

输入

参数位置类型必填默认/枚举说明
topicIdpathstring是—要订阅的主题 ID。
queriesquerystring[]否默认 []查询字符串数组,由 SDK 的 Query 构造器生成(形如 limit(25)、equal("name","x"));支持过滤、排序、分页(limit / cursorAfter / cursorBefore);可过滤属性:targetId、topicId、userId、providerType。最多 100 条、每条最长 4096 字符。
searchquerystring否—搜索词,模糊过滤列表结果。最长 256 字符。
totalqueryboolean否默认 true设为 false 时跳过总数计算,返回的 total 固定为 0。

输出:200,模型 subscriberList:total(匹配总数,total=false 时不计算)+ subscribers[](当前页数据)。

元素模型 subscriber 关键字段:

字段类型说明
$idstring订阅者 ID。
$createdAtstring订阅创建时间(ISO 8601)。
$updatedAtstring订阅更新时间(ISO 8601)。
targetIdstring目标 ID。
targetobject消息目标对象。
topicIdstring主题 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)

参数位置类型必填默认/枚举说明
subscriberIdbodystring是—订阅者 ID。可自定义新 ID。
targetIdbodystring是—要关联到该主题的目标 ID(来自 users 的消息目标)。
topicIdpathstring是—要订阅的主题 ID。

输出:201,模型 subscriber,字段:

字段类型说明
$idstring订阅者 ID。
$createdAtstring订阅创建时间(ISO 8601)。
$updatedAtstring订阅更新时间(ISO 8601)。
targetIdstring目标 ID。
targetobject消息目标对象。
userIdstring订阅者关联的用户 ID。
userNamestring订阅者关联的用户名。
topicIdstring主题 ID。
providerTypestring目标通道类型: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。)

输入

参数位置类型必填默认/枚举说明
topicIdpathstring是—要订阅的主题 ID。
subscriberIdpathstring是—订阅者 ID。

输出:200,模型 subscriber(完整字段见前文),关键字段:

字段类型说明
$idstring订阅者 ID。
$createdAtstring订阅创建时间(ISO 8601)。
$updatedAtstring订阅更新时间(ISO 8601)。
targetIdstring目标 ID。
targetobject消息目标对象。
topicIdstring主题 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。)

输入

参数位置类型必填默认/枚举说明
topicIdpathstring是—要订阅的主题 ID。
subscriberIdpathstring是—订阅者 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。)

输入

参数位置类型必填默认/枚举说明
subscriberIdpathstring是—订阅者 ID。
queriesquerystring[]否默认 []查询字符串数组,由 SDK 的 Query 构造器生成(形如 limit(25)、equal("name","x"));仅支持 limit / offset 两个方法。
totalqueryboolean否默认 true设为 false 时跳过总数计算,返回的 total 固定为 0。

输出:200,模型 logList:total(匹配总数,total=false 时不计算)+ logs[](当前页数据)。

元素模型 log 关键字段:

字段类型说明
eventstring事件名。
userIdstring触发该日志的用户 ID。被代理(impersonation)时记录代理发起者而非被代理用户。
userEmailstring触发该日志的用户邮箱。
modestring事件触发时的 API 模式(admin/key 等)。
ipstring事件发生时的来源 IP。
timestring日志创建时间(ISO 8601)。
clientNamestring客户端名称。
countryNamestring国家/地区名称。

调用示例:

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

错误与边界

与 Server SDK 的对应

service.method端点
Messaging.listMessages / getMessage / deleteMessageGET /messaging/messages、`GETDELETE .../messages/{messageId}`
Messaging.createEmail / updateEmail、createSms / updateSms、createPush / updatePush`POSTPATCH /messaging/messages/{emailsmspush}`
Messaging.listTargets / listMessageLogsGET .../messages/{messageId}/targets、.../logs
Messaging.listProviders / getProvider / deleteProvider / listProviderLogs/messaging/providers*
Messaging.createApnsProvider … createVonageProvider(11 种)、updateApnsProvider … updateVonageProvider`POSTPATCH /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

事实源