Message Push API
Unified messaging surface: message providers (email / SMS / push channels), topics and subscribers, creation, modification, and delivery logs of draft and scheduled messages (email / sms / push).
Service and resource boundaries
The Messaging API (/v1/messaging/*) provides unified notification orchestration and delivery auditing across channels (Email, SMS, mobile Push): it supports configuring multi-vendor channel providers (SMTP / SendGrid / Mailgun / Resend, Twilio / Vonage / Telesign / MSG91 / TextMagic, APNs / FCM), selecting recipients via a three-layer addressing model combining Topic, User ID, and device Target, and supports saving drafts (Draft), scheduled sending (scheduledAt), and delivery log tracking.
Resources and Base Paths
Base URL:
https://<your-endpoint>/v1, path prefix/messaging.Resources:
provider({providerId}),topic({topicId}),subscriber({subscriberId}),message({messageId}).Recipient resolution: a message can specify
topics(topic),users(user, whose targets are resolved automatically), andtargets(exact target) at the same time; the three can be combined.
Authentication and Permissions
See General conventions for authentication and request header conventions. Scopes for this domain: messages.read / messages.write (messages), providers.read / providers.write (providers), topics.read / topics.write (topics), subscribers.read / subscribers.write (subscribers).
Endpoint overview
The Messaging module contains 46 endpoints in total, grouped by resource into three major groups: message creation (Email / SMS / Push), draft update, deletion, and delivery target/log queries (11); provider-specific creation, update, and management endpoints for 11 upstream providers (Providers) across the three channel types (25); and management endpoints for topics (Topics) and subscribers (Subscribers) (10).
Endpoint List
Messages (messages)
| Method + path | Purpose |
|---|---|
GET /messaging/messages | List messages |
POST /messaging/messages/email | Create email |
PATCH /messaging/messages/email/{messageId} | Update email |
POST /messaging/messages/sms | Create SMS |
PATCH /messaging/messages/sms/{messageId} | Update SMS |
POST /messaging/messages/push | Create push notification |
PATCH /messaging/messages/push/{messageId} | Update push notification |
GET /messaging/messages/{messageId} | Get message |
DELETE /messaging/messages/{messageId} | Delete message |
GET /messaging/messages/{messageId}/targets | List targets resolved for a message |
GET /messaging/messages/{messageId}/logs | Message delivery logs |
Providers (providers)
| Method + path | Purpose |
|---|---|
GET /messaging/providers | List providers |
POST /messaging/providers/apns|fcm | Create push provider (APNS / FCM) |
POST /messaging/providers/mailgun|sendgrid|smtp|resend | Create email provider |
POST /messaging/providers/twilio|vonage|telesign|msg91|textmagic | Create SMS provider |
PATCH /messaging/providers/{type}/{providerId} | Update provider of the corresponding type |
GET /messaging/providers/{providerId} | Get provider |
DELETE /messaging/providers/{providerId} | Delete provider |
GET /messaging/providers/{providerId}/logs | Provider send logs |
Topics and subscribers (topics / subscribers)
| Method + path | Purpose |
|---|---|
GET /messaging/topics | List topics |
POST /messaging/topics | Create topic |
GET /messaging/topics/{topicId} | Get topic |
PATCH /messaging/topics/{topicId} | Update topic |
DELETE /messaging/topics/{topicId} | Delete topic |
GET /messaging/topics/{topicId}/logs | Topic delivery logs |
GET /messaging/topics/{topicId}/subscribers | List subscribers |
POST /messaging/topics/{topicId}/subscribers | Create subscription |
GET /messaging/topics/{topicId}/subscribers/{subscriberId} | Get subscription |
DELETE /messaging/topics/{topicId}/subscribers/{subscriberId} | Unsubscribe |
GET /messaging/subscribers/{subscriberId}/logs | Subscriber delivery logs |
Endpoint details
Immediate sending, scheduled sending, and the draft state machine: when creating a message, if
draft=true, the message is only stored in thedraftstate and does not enter the sending queue; ifdraft=falseand noscheduledAtis specified (or the time is earlier than the current moment), the message immediately enters theprocessingqueue for asynchronous delivery; if a futurescheduledAt(ISO 8601) is specified, the message stays in thescheduledstate and, until it becomes due, its content or recipients may be modified viaPATCH.
Requests and Responses
The following sections give the input/output specifications, copyable curl call examples, and response examples for each endpoint. Path prefix /v1; the request headers X-Appwrite-Project: <YOUR_PROJECT_ID> and X-Appwrite-Key: <YOUR_API_KEY> are consistent across all endpoints and are not explained individually in the examples.
Messages
GET /v1/messaging/messages
List all messages in the project with pagination; supports filtering by status, scheduled time, etc., and keyword search (scope messages.read. SDK: Messages.listMessages.)
Input
| Parameter | Location | Type | Required | Default/enum | Description |
|---|---|---|---|---|---|
queries | query | string[] | No | Default [] | Array of query strings generated by the SDK's Query constructor (e.g. limit(25), equal("name","x")); supports filtering, sorting, and pagination (limit / cursorAfter / cursorBefore); filterable attributes: scheduledAt, deliveredAt, deliveredTotal, status, description, providerType. Up to 100 items, each at most 4096 characters. |
search | query | string | No | — | Search term that fuzzily filters list results. Up to 256 characters. |
total | query | boolean | No | Default true | When set to false, skips total count calculation and the returned total is fixed at 0. |
Output: 200, model messageList: total (total number of matches, not calculated when total=false) + messages[] (current page of data).
Key fields of the element model message:
| Field | Type | Description |
|---|---|---|
$id | string | Message ID. |
$createdAt | string | Message creation time (ISO 8601). |
$updatedAt | string | Message update time (ISO 8601). |
providerType | string | Message channel type (email / sms / push). |
topics | string[] | List of topic IDs as recipients. |
users | string[] | List of user IDs as recipients. |
targets | string[] | List of target IDs as recipients. |
scheduledAt | string | Message scheduled send time. |
deliveredAt | string | Message actual delivery time. |
deliveryErrors | string[] | List of delivery errors (if any). |
deliveredTotal | integer | Number of recipients successfully delivered to. |
data | object | Message data. |
status | string | Delivery status. |
Call example:
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"Response example:
{
"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
Create an email message: draft=true saves as draft, scheduledAt schedules, otherwise it enters the delivery flow (scope messages.write. SDK: Messages.createEmail.)
Input (application/json)
| Parameter | Location | Type | Required | Default/enum | Description |
|---|---|---|---|---|---|
messageId | body | string | Yes | — | Message ID. Can be custom, or generated with the SDK's ID.unique(); only a-z, A-Z, 0-9, periods, hyphens, and underscores are allowed, and it cannot start with a special character. At most 36 characters. |
subject | body | string | Yes | — | Email subject. |
content | body | string | Yes | — | Email body. |
topics | body | string[] | No | — | List of topic IDs. |
users | body | string[] | No | — | List of user IDs. |
targets | body | string[] | No | — | List of target IDs. |
cc | body | string[] | No | — | Array of target IDs for CC. |
bcc | body | string[] | No | — | Array of target IDs for BCC. |
attachments | body | string[] | No | — | Array of composite IDs for email attachments, in the format <BUCKET_ID>:<FILE_ID> (files must already be uploaded to Storage). |
draft | body | boolean | No | — | Whether it is a draft. |
html | body | boolean | No | — | Whether the body is HTML. |
scheduledAt | body | string | No | Can be null | Message scheduled send time (ISO 8601). Must be a future time. |
Output: 201, model message, fields:
| Field | Type | Description |
|---|---|---|
$id | string | Message ID. |
$createdAt | string | Message creation time (ISO 8601). |
$updatedAt | string | Message update time (ISO 8601). |
providerType | string | Message channel type (email / sms / push). |
topics | string[] | List of topic IDs as recipients. |
users | string[] | List of user IDs as recipients. |
targets | string[] | List of target IDs as recipients. |
scheduledAt | string | Message scheduled send time. |
deliveredAt | string | Message actual delivery time. |
deliveryErrors | string[] | List of delivery errors (if any). |
deliveredTotal | integer | Number of recipients successfully delivered to. |
data | object | Message data. |
status | string | Delivery status. |
Call example:
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
}'Response excerpt (fields unrelated to this operation omitted):
{
"$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}
Update an email message: only messages in the draft state can be modified; messages already in processing / sent / failed cannot be modified (scope messages.write. SDK: Messages.updateEmail.)
Input (application/json)
| Parameter | Location | Type | Required | Default/enum | Description |
|---|---|---|---|---|---|
topics | body | string[] | No | Can be null | List of topic IDs. |
users | body | string[] | No | Can be null | List of user IDs. |
targets | body | string[] | No | Can be null | List of target IDs. |
subject | body | string | No | Can be null | Email subject. |
content | body | string | No | Can be null | Email body. |
draft | body | boolean | No | Can be null | Whether it is a draft. |
html | body | boolean | No | Can be null | Whether the body is HTML. |
cc | body | string[] | No | Can be null | Array of target IDs for CC. |
bcc | body | string[] | No | Can be null | Array of target IDs for BCC. |
scheduledAt | body | string | No | Can be null | Message scheduled send time (ISO 8601). Must be a future time. |
attachments | body | string[] | No | Can be null | Array of composite IDs for email attachments, in the format <BUCKET_ID>:<FILE_ID> (files must already be uploaded to Storage). |
messageId | path | string | Yes | — | Message ID. |
Output: 200, model message (full fields described above), key fields:
| Field | Type | Description |
|---|---|---|
$id | string | Message ID. |
$createdAt | string | Message creation time (ISO 8601). |
$updatedAt | string | Message update time (ISO 8601). |
providerType | string | Message channel type (email / sms / push). |
topics | string[] | List of topic IDs as recipients. |
users | string[] | List of user IDs as recipients. |
targets | string[] | List of target IDs as recipients. |
scheduledAt | string | Message scheduled send time. |
deliveredAt | string | Message actual delivery time. |
deliveryErrors | string[] | List of delivery errors (if any). |
deliveredTotal | integer | Number of recipients successfully delivered to. |
data | object | Message data. |
status | string | Delivery status. |
Call example:
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
}'Response example:
{
"$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
Create an SMS message. This endpoint is marked as deprecated in the spec (still available in v2.6.0, and the SDK retains the corresponding method). (Scope messages.write. SDK: Messages.createSms.)
Input (application/json)
| Parameter | Location | Type | Required | Default/enum | Description |
|---|---|---|---|---|---|
messageId | body | string | Yes | — | Message ID. Can be custom, or generated with the SDK's ID.unique(); only a-z, A-Z, 0-9, periods, hyphens, and underscores are allowed, and it cannot start with a special character. At most 36 characters. |
content | body | string | Yes | — | SMS body. |
topics | body | string[] | No | — | List of topic IDs. |
users | body | string[] | No | — | List of user IDs. |
targets | body | string[] | No | — | List of target IDs. |
draft | body | boolean | No | — | Whether it is a draft. |
scheduledAt | body | string | No | Can be null | Message scheduled send time (ISO 8601). Must be a future time. |
Output: 201, model message (full fields described above), key fields:
| Field | Type | Description |
|---|---|---|
$id | string | Message ID. |
$createdAt | string | Message creation time (ISO 8601). |
$updatedAt | string | Message update time (ISO 8601). |
providerType | string | Message channel type (email / sms / push). |
topics | string[] | List of topic IDs as recipients. |
users | string[] | List of user IDs as recipients. |
targets | string[] | List of target IDs as recipients. |
scheduledAt | string | Message scheduled send time. |
deliveredAt | string | Message actual delivery time. |
deliveryErrors | string[] | List of delivery errors (if any). |
deliveredTotal | integer | Number of recipients successfully delivered to. |
data | object | Message data. |
status | string | Delivery status. |
Call example:
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
}'Response excerpt (unrelated fields omitted):
{
"$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}
Update an SMS message: only messages in the draft state can be modified. This endpoint is marked as deprecated in the spec (still available in v2.6.0, and the SDK retains the corresponding method). (Scope messages.write. SDK: Messages.updateSms.)
Input (application/json)
| Parameter | Location | Type | Required | Default/enum | Description |
|---|---|---|---|---|---|
topics | body | string[] | No | Can be null | List of topic IDs. |
users | body | string[] | No | Can be null | List of user IDs. |
targets | body | string[] | No | Can be null | List of target IDs. |
content | body | string | No | Can be null | Email body. |
draft | body | boolean | No | Can be null | Whether it is a draft. |
scheduledAt | body | string | No | Can be null | Message scheduled send time (ISO 8601). Must be a future time. |
messageId | path | string | Yes | — | Message ID. |
Output: 200, model message (full fields described above), key fields:
| Field | Type | Description |
|---|---|---|
$id | string | Message ID. |
$createdAt | string | Message creation time (ISO 8601). |
$updatedAt | string | Message update time (ISO 8601). |
providerType | string | Message channel type (email / sms / push). |
topics | string[] | List of topic IDs as recipients. |
users | string[] | List of user IDs as recipients. |
targets | string[] | List of target IDs as recipients. |
scheduledAt | string | Message scheduled send time. |
deliveredAt | string | Message actual delivery time. |
deliveryErrors | string[] | List of delivery errors (if any). |
deliveredTotal | integer | Number of recipients successfully delivered to. |
data | object | Message data. |
status | string | Delivery status. |
Call example:
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>"
}'Response excerpt (unrelated fields omitted):
{
"$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
Create a push notification: content fields take effect per Android / iOS / Web platform respectively (scope messages.write. SDK: Messages.createPush.)
Input (application/json)
| Parameter | Location | Type | Required | Default/enum | Description |
|---|---|---|---|---|---|
messageId | body | string | Yes | — | Message ID. Can be custom, or generated with the SDK's ID.unique(); only a-z, A-Z, 0-9, periods, hyphens, and underscores are allowed, and it cannot start with a special character. At most 36 characters. |
title | body | string | No | — | Push title. |
body | body | string | No | — | Push body. |
topics | body | string[] | No | — | List of topic IDs. |
users | body | string[] | No | — | List of user IDs. |
targets | body | string[] | No | — | List of target IDs. |
data | body | object | No | Can be null | Push custom key-value data. |
action | body | string | No | — | Push click action. |
image | body | string | No | — | Push large image. Must be the composite ID of a jpeg/png image in Storage, in the format <BUCKET_ID>:<FILE_ID>. |
icon | body | string | No | — | Push icon. Only effective on Android / Web. |
sound | body | string | No | — | Push sound. Only effective on Android / iOS. |
color | body | string | No | — | Push color. Only effective on Android. |
tag | body | string | No | — | Push tag (collapses notifications with the same tag). Only effective on Android. |
badge | body | integer | No | — | App badge count. Only effective on iOS. |
draft | body | boolean | No | — | Whether it is a draft. |
scheduledAt | body | string | No | Can be null | Message scheduled send time (ISO 8601). Must be a future time. |
contentAvailable | body | boolean | No | — | Delivers silently in the background when set to true. Only effective on iOS. |
critical | body | boolean | No | — | Marks the notification as critical when set to true, requiring the app to have the critical notification entitlement. Only effective on iOS. |
priority | body | string | No | normal / high | Push priority. normal takes device status into account and delivery may be delayed; high always attempts immediate delivery. |
imageInternal | body | boolean | No | — | true when the image is stored in the internal default bucket. |
Output: 201, model message (full fields described above), key fields:
| Field | Type | Description |
|---|---|---|
$id | string | Message ID. |
$createdAt | string | Message creation time (ISO 8601). |
$updatedAt | string | Message update time (ISO 8601). |
providerType | string | Message channel type (email / sms / push). |
topics | string[] | List of topic IDs as recipients. |
users | string[] | List of user IDs as recipients. |
targets | string[] | List of target IDs as recipients. |
scheduledAt | string | Message scheduled send time. |
deliveredAt | string | Message actual delivery time. |
deliveryErrors | string[] | List of delivery errors (if any). |
deliveredTotal | integer | Number of recipients successfully delivered to. |
data | object | Message data. |
status | string | Delivery status. |
Call example:
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
}'Response excerpt (unrelated fields omitted):
{
"$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}
Update push notification: only changeable in draft status (scope messages.write. SDK: Messages.updatePush.)
Input (application/json)
| Parameter | Location | Type | Required | Default/enum | Description |
|---|---|---|---|---|---|
topics | body | string[] | No | Can be null | List of topic IDs. |
users | body | string[] | No | Can be null | List of user IDs. |
targets | body | string[] | No | Can be null | List of target IDs. |
title | body | string | No | Can be null | Push title. |
body | body | string | No | Can be null | Push body. |
data | body | object | No | Can be null | Push additional data. |
action | body | string | No | Can be null | Push click action. |
image | body | string | No | Can be null | Push large image. Must be the composite ID of a jpeg/png image in Storage, in the format <BUCKET_ID>:<FILE_ID>. |
icon | body | string | No | Can be null | Push icon. Only effective on Android / Web. |
sound | body | string | No | Can be null | Push sound. Only effective on Android / iOS. |
color | body | string | No | Can be null | Push color. Only effective on Android. |
tag | body | string | No | Can be null | Push tag (collapses notifications with the same tag). Only effective on Android. |
badge | body | integer | No | Can be null | App badge count. Only effective on iOS. |
draft | body | boolean | No | Can be null | Whether it is a draft. |
scheduledAt | body | string | No | Can be null | Message scheduled send time (ISO 8601). Must be a future time. |
contentAvailable | body | boolean | No | Can be null | Delivers silently in the background when set to true. Only effective on iOS. |
critical | body | boolean | No | Can be null | Marks the notification as critical when set to true, requiring the app to have the critical notification entitlement. Only effective on iOS. |
priority | body | string | No | normal / high; can be null | Push priority. normal takes device battery status into account and sending may be delayed; high always attempts immediate delivery. |
imageInternal | body | boolean | No | — | true when the image is stored in the internal default bucket. |
messageId | path | string | Yes | — | Message ID. |
Output: 200, model message (full fields described above), key fields:
| Field | Type | Description |
|---|---|---|
$id | string | Message ID. |
$createdAt | string | Message creation time (ISO 8601). |
$updatedAt | string | Message update time (ISO 8601). |
providerType | string | Message channel type (email / sms / push). |
topics | string[] | List of topic IDs as recipients. |
users | string[] | List of user IDs as recipients. |
targets | string[] | List of target IDs as recipients. |
scheduledAt | string | Message scheduled send time. |
deliveredAt | string | Message actual delivery time. |
deliveryErrors | string[] | List of delivery errors (if any). |
deliveredTotal | integer | Number of recipients successfully delivered to. |
data | object | Message data. |
status | string | Delivery status. |
Call example:
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}"
}'Response excerpt (unrelated fields omitted):
{
"$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}
Read a single message and its delivery status (status, deliveredTotal, deliveryErrors) (scope messages.read. SDK: Messages.getMessage.)
Input
| Parameter | Location | Type | Required | Default/enum | Description |
|---|---|---|---|---|---|
messageId | path | string | Yes | — | Message ID. |
Output: 200, model message (full fields described above), key fields:
| Field | Type | Description |
|---|---|---|
$id | string | Message ID. |
$createdAt | string | Message creation time (ISO 8601). |
$updatedAt | string | Message update time (ISO 8601). |
providerType | string | Message channel type (email / sms / push). |
topics | string[] | List of topic IDs as recipients. |
users | string[] | List of user IDs as recipients. |
targets | string[] | List of target IDs as recipients. |
scheduledAt | string | Message scheduled send time. |
deliveredAt | string | Message actual delivery time. |
deliveryErrors | string[] | List of delivery errors (if any). |
deliveredTotal | integer | Number of recipients successfully delivered to. |
data | object | Message data. |
status | string | Delivery status. |
Call example:
curl "https://<your-endpoint>/v1/messaging/messages/<MESSAGE_ID>" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>"Response example:
{
"$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}
Delete message: sent messages are not recalled, only the record is deleted; drafts/scheduled messages have their delivery canceled (scope messages.write. SDK: Messages.delete.)
Input
| Parameter | Location | Type | Required | Default/enum | Description |
|---|---|---|---|---|---|
messageId | path | string | Yes | — | Message ID. |
Output: 204 No response body.
Call example:
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>"Response example:
_Binary stream or no response body (see output description)._
GET /v1/messaging/messages/{messageId}/targets
List the delivery targets explicitly specified in the message targets; topics and users are not expanded, and an empty targets list returns no targets (scope messages.read. SDK: Messages.listTargets.)
Input
| Parameter | Location | Type | Required | Default/enum | Description |
|---|---|---|---|---|---|
messageId | path | string | Yes | — | Message ID. |
queries | query | string[] | No | Defaults to [] | Array of query strings, generated by the SDK's Query constructor (in the form of limit(25), equal("name","x")); supports filtering, sorting, and pagination (limit / cursorAfter / cursorBefore); filterable attributes: userId, providerId, identifier, providerType. At most 100 queries, each at most 4096 characters. |
total | query | boolean | No | Default true | When set to false, skips total count calculation and the returned total is fixed at 0. |
Output: 200, model targetList: total (total number of matches, not calculated when total=false) + targets[] (current page of data).
Key fields of the element model target:
| Field | Type | Description |
|---|---|---|
$id | string | Target ID. |
$createdAt | string | Target creation time (ISO 8601). |
$updatedAt | string | Target update time (ISO 8601). |
name | string | Target name. |
userId | string | User ID. |
providerType | string | Target channel type: email / sms / push. |
identifier | string | Target identifier (email address / phone number / push token). |
expired | boolean | Whether the target has expired. |
Call example:
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)"Response example:
{
"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
List the delivery logs of the message (only limit/offset pagination is supported) (scope messages.read. SDK: Logs.listMessageLogs.)
Input
| Parameter | Location | Type | Required | Default/enum | Description |
|---|---|---|---|---|---|
messageId | path | string | Yes | — | Message ID. |
queries | query | string[] | No | Defaults to [] | Array of query strings, generated by the SDK's Query constructor (in the form of limit(25), equal("name","x")); only the limit / offset methods are supported. |
total | query | boolean | No | Default true | When set to false, skips total count calculation and the returned total is fixed at 0. |
Output: 200, model logList: total (total number of matches, not calculated when total=false) + logs[] (current page of data).
Key fields of the element model log:
| Field | Type | Description |
|---|---|---|
event | string | Event name. |
userId | string | ID of the user who triggered this log. When impersonation is used, the impersonator is recorded rather than the impersonated user. |
userEmail | string | Email of the user who triggered this log. |
mode | string | API mode when the event was triggered (admin/key, etc.). |
ip | string | Source IP when the event occurred. |
time | string | Log creation time (ISO 8601). |
clientName | string | Client name. |
countryName | string | Country/region name. |
Call example:
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)"Response example:
{
"total": 5,
"logs": ""
}Providers
GET /v1/messaging/providers
List all messaging providers in the project with pagination (scope providers.read. SDK: Providers.listProviders.)
Input
| Parameter | Location | Type | Required | Default/enum | Description |
|---|---|---|---|---|---|
queries | query | string[] | No | Defaults to [] | Array of query strings, generated by the SDK's Query constructor (in the form of limit(25), equal("name","x")); supports filtering, sorting, and pagination (limit / cursorAfter / cursorBefore); filterable attributes: name, provider, type, enabled. At most 100 queries, each at most 4096 characters. |
search | query | string | No | — | Search term that fuzzily filters list results. Up to 256 characters. |
total | query | boolean | No | Default true | When set to false, skips total count calculation and the returned total is fixed at 0. |
Output: 200, model providerList: total (total number of matches, not calculated when total=false) + providers[] (current page of data).
Key fields of the element model provider:
| Field | Type | Description |
|---|---|---|
$id | string | Provider ID. |
$createdAt | string | Provider creation time (ISO 8601). |
$updatedAt | string | Provider update time (ISO 8601). |
name | string | Provider instance name. |
provider | string | Provider service identifier. |
enabled | boolean | Whether the provider is enabled. |
type | string | Provider channel type. |
credentials | object | Provider credentials; fields and response content vary by provider and deployment. |
options | object | Provider options. |
Call example:
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"Response excerpt:
{
"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
Create an Apple Push Notification service (APNS) provider: uses the trio of .p8 key credentials (authKey/authKeyId/teamId). This endpoint is marked as deprecated in the spec (still available in v2.6.0; the SDK keeps the corresponding method). (scope providers.write. SDK: Providers.createApnsProvider.)
Input (application/json)
| Parameter | Location | Type | Required | Default/enum | Description |
|---|---|---|---|---|---|
providerId | body | string | Yes | — | Provider ID. Can be customized, or generated with the SDK's ID.unique(); only a-z, A-Z, 0-9, periods, hyphens, and underscores are allowed, and it cannot start with a special character. At most 36 characters. |
name | body | string | Yes | — | Provider name. |
authKey | body | string | No | — | APNS authentication key (.p8 private key content). |
authKeyId | body | string | No | — | APNS key ID. |
teamId | body | string | No | — | APNS team ID. |
bundleId | body | string | No | — | App Bundle ID. |
sandbox | body | boolean | No | — | Whether to use the APNS sandbox environment. |
enabled | body | boolean | No | Can be null | Whether enabled. |
Output: 201, model provider, fields:
| Field | Type | Description |
|---|---|---|
$id | string | Provider ID. |
$createdAt | string | Provider creation time (ISO 8601). |
$updatedAt | string | Provider update time (ISO 8601). |
name | string | Provider instance name. |
provider | string | Provider service identifier. |
enabled | boolean | Whether the provider is enabled. |
type | string | Provider channel type. |
credentials | object | Provider credentials; fields and response content vary by provider and deployment. |
options | object | Provider options. |
Call example:
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
}'Response excerpt (unrelated fields omitted):
{
"$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}
Update APNS provider: fields not provided keep their current values. This endpoint is marked as deprecated in the spec (still available in v2.6.0; the SDK keeps the corresponding method). (scope providers.write. SDK: Providers.updateApnsProvider.)
Input (application/json)
| Parameter | Location | Type | Required | Default/enum | Description |
|---|---|---|---|---|---|
name | body | string | No | — | Provider name. |
enabled | body | boolean | No | Can be null | Whether enabled. |
authKey | body | string | No | — | APNS authentication key (.p8 private key content). |
authKeyId | body | string | No | — | APNS key ID. |
teamId | body | string | No | — | APNS team ID. |
bundleId | body | string | No | — | App Bundle ID. |
sandbox | body | boolean | No | Can be null | Whether to use the APNS sandbox environment. |
providerId | path | string | Yes | — | Provider ID. |
Output: 200, model provider (full fields described above), key fields:
| Field | Type | Description |
|---|---|---|
$id | string | Provider ID. |
$createdAt | string | Provider creation time (ISO 8601). |
$updatedAt | string | Provider update time (ISO 8601). |
name | string | Provider instance name. |
provider | string | Provider service identifier. |
enabled | boolean | Whether the provider is enabled. |
type | string | Provider channel type. |
credentials | object | Provider credentials; fields and response content vary by provider and deployment. |
options | object | Provider options. |
Call example:
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
}'Response excerpt (unrelated fields omitted):
{
"$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
Create a Firebase Cloud Messaging (FCM) provider: submit the service account JSON. This endpoint is marked as deprecated in the spec (still available in v2.6.0; the SDK keeps the corresponding method). (scope providers.write. SDK: Providers.createFcmProvider.)
Input (application/json)
| Parameter | Location | Type | Required | Default/enum | Description |
|---|---|---|---|---|---|
providerId | body | string | Yes | — | Provider ID. Can be customized, or generated with the SDK's ID.unique(); only a-z, A-Z, 0-9, periods, hyphens, and underscores are allowed, and it cannot start with a special character. At most 36 characters. |
name | body | string | Yes | — | Provider name. |
serviceAccountJSON | body | object | No | Can be null | FCM service account JSON. |
enabled | body | boolean | No | Can be null | Whether enabled. |
Output: 201, model provider (full fields described above), key fields:
| Field | Type | Description |
|---|---|---|
$id | string | Provider ID. |
$createdAt | string | Provider creation time (ISO 8601). |
$updatedAt | string | Provider update time (ISO 8601). |
name | string | Provider instance name. |
provider | string | Provider service identifier. |
enabled | boolean | Whether the provider is enabled. |
type | string | Provider channel type. |
credentials | object | Provider credentials; fields and response content vary by provider and deployment. |
options | object | Provider options. |
Call example:
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
}'Response excerpt (unrelated fields omitted):
{
"$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}
Update FCM provider. This endpoint is marked as deprecated in the spec (still available in v2.6.0; the SDK keeps the corresponding method). (scope providers.write. SDK: Providers.updateFcmProvider.)
Input (application/json)
| Parameter | Location | Type | Required | Default/enum | Description |
|---|---|---|---|---|---|
name | body | string | No | — | Provider name. |
enabled | body | boolean | No | Can be null | Whether enabled. |
serviceAccountJSON | body | object | No | Can be null | FCM service account JSON. |
providerId | path | string | Yes | — | Provider ID. |
Output: 200, model provider (full fields described above), key fields:
| Field | Type | Description |
|---|---|---|
$id | string | Provider ID. |
$createdAt | string | Provider creation time (ISO 8601). |
$updatedAt | string | Provider update time (ISO 8601). |
name | string | Provider instance name. |
provider | string | Provider service identifier. |
enabled | boolean | Whether the provider is enabled. |
type | string | Provider channel type. |
credentials | object | Provider credentials; fields and response content vary by provider and deployment. |
options | object | Provider options. |
Call example:
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"
}
}'Response excerpt (unrelated fields omitted):
{
"$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
Create a Mailgun email provider (scope providers.write. SDK: Providers.createMailgunProvider.)
Input (application/json)
| Parameter | Location | Type | Required | Default/enum | Description |
|---|---|---|---|---|---|
providerId | body | string | Yes | — | Provider ID. Can be customized, or generated with the SDK's ID.unique(); only a-z, A-Z, 0-9, periods, hyphens, and underscores are allowed, and it cannot start with a special character. At most 36 characters. |
name | body | string | Yes | — | Provider name. |
apiKey | body | string | No | — | Mailgun API Key. |
domain | body | string | No | — | Mailgun domain. |
isEuRegion | body | boolean | No | Can be null | Whether to use the Mailgun EU region. |
fromName | body | string | No | — | Sender name. |
fromEmail | body | string | No | — | Sender email address. |
replyToName | body | string | No | — | Email Reply-To name. Defaults to the sender name; must be provided together with the Reply-To email address. |
replyToEmail | body | string | No | — | Email Reply-To address. Defaults to the sender email address; must be provided together with the Reply-To name. |
enabled | body | boolean | No | Can be null | Whether enabled. |
Output: 201, model provider (full fields described above), key fields:
| Field | Type | Description |
|---|---|---|
$id | string | Provider ID. |
$createdAt | string | Provider creation time (ISO 8601). |
$updatedAt | string | Provider update time (ISO 8601). |
name | string | Provider instance name. |
provider | string | Provider service identifier. |
enabled | boolean | Whether the provider is enabled. |
type | string | Provider channel type. |
credentials | object | Provider credentials; fields and response content vary by provider and deployment. |
options | object | Provider options. |
Call example:
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
}'Response excerpt (unrelated fields omitted):
{
"$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}
Update Mailgun provider (scope providers.write. SDK: Providers.updateMailgunProvider.)
Input (application/json)
| Parameter | Location | Type | Required | Default/enum | Description |
|---|---|---|---|---|---|
name | body | string | No | — | Provider name. |
apiKey | body | string | No | — | Mailgun API Key. |
domain | body | string | No | — | Mailgun domain. |
isEuRegion | body | boolean | No | Can be null | Whether to use the Mailgun EU region. |
enabled | body | boolean | No | Can be null | Whether enabled. |
fromName | body | string | No | — | Sender name. |
fromEmail | body | string | No | — | Sender email address. |
replyToName | body | string | No | — | Email Reply-To name. Defaults to the sender name. |
replyToEmail | body | string | No | — | Email Reply-To address. Defaults to the sender email address. |
providerId | path | string | Yes | — | Provider ID. |
Output: 200, model provider (full fields described above), key fields:
| Field | Type | Description |
|---|---|---|
$id | string | Provider ID. |
$createdAt | string | Provider creation time (ISO 8601). |
$updatedAt | string | Provider update time (ISO 8601). |
name | string | Provider instance name. |
provider | string | Provider service identifier. |
enabled | boolean | Whether the provider is enabled. |
type | string | Provider channel type. |
credentials | object | Provider credentials; fields and response content vary by provider and deployment. |
options | object | Provider options. |
Call example:
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"
}'Response excerpt (unrelated fields omitted):
{
"$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
Create MSG91 SMS provider (scope providers.write. SDK: Providers.createMsg91Provider.)
Input (application/json)
| Parameter | Location | Type | Required | Default/enum | Description |
|---|---|---|---|---|---|
providerId | body | string | Yes | — | Provider ID. Can be customized, or generated with the SDK's ID.unique(); only a-z, A-Z, 0-9, periods, hyphens, and underscores are allowed, and it cannot start with a special character. At most 36 characters. |
name | body | string | Yes | — | Provider name. |
templateId | body | string | No | — | MSG91 template ID. |
senderId | body | string | No | — | MSG91 sender ID. |
authKey | body | string | No | — | MSG91 auth secret. |
enabled | body | boolean | No | Can be null | Whether enabled. |
Output: 201, model provider (full fields described above), key fields:
| Field | Type | Description |
|---|---|---|
$id | string | Provider ID. |
$createdAt | string | Provider creation time (ISO 8601). |
$updatedAt | string | Provider update time (ISO 8601). |
name | string | Provider instance name. |
provider | string | Provider service identifier. |
enabled | boolean | Whether the provider is enabled. |
type | string | Provider channel type. |
credentials | object | Provider credentials; fields and response content vary by provider and deployment. |
options | object | Provider options. |
Call example:
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
}'Response excerpt (unrelated fields omitted):
{
"$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}
Update MSG91 provider (scope providers.write. SDK: Providers.updateMsg91Provider.)
Input (application/json)
| Parameter | Location | Type | Required | Default/enum | Description |
|---|---|---|---|---|---|
name | body | string | No | — | Provider name. |
enabled | body | boolean | No | Can be null | Whether enabled. |
templateId | body | string | No | — | MSG91 template ID. |
senderId | body | string | No | — | MSG91 sender ID. |
authKey | body | string | No | — | MSG91 auth secret. |
providerId | path | string | Yes | — | Provider ID. |
Output: 200, model provider (full fields described above), key fields:
| Field | Type | Description |
|---|---|---|
$id | string | Provider ID. |
$createdAt | string | Provider creation time (ISO 8601). |
$updatedAt | string | Provider update time (ISO 8601). |
name | string | Provider instance name. |
provider | string | Provider service identifier. |
enabled | boolean | Whether the provider is enabled. |
type | string | Provider channel type. |
credentials | object | Provider credentials; fields and response content vary by provider and deployment. |
options | object | Provider options. |
Call example:
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-----"
}'Response excerpt (unrelated fields omitted):
{
"$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
Create Resend email provider (scope providers.write. SDK: Providers.createResendProvider.)
Input (application/json)
| Parameter | Location | Type | Required | Default/enum | Description |
|---|---|---|---|---|---|
providerId | body | string | Yes | — | Provider ID. Can be customized, or generated with the SDK's ID.unique(); only a-z, A-Z, 0-9, periods, hyphens, and underscores are allowed, and it cannot start with a special character. At most 36 characters. |
name | body | string | Yes | — | Provider name. |
apiKey | body | string | No | — | Resend API key. |
fromName | body | string | No | — | Sender name. |
fromEmail | body | string | No | — | Sender email address. |
replyToName | body | string | No | — | Email Reply-To name. Defaults to the sender name. |
replyToEmail | body | string | No | — | Email Reply-To address. Defaults to the sender email address. |
enabled | body | boolean | No | Can be null | Whether enabled. |
Output: 201, model provider (full fields described above), key fields:
| Field | Type | Description |
|---|---|---|
$id | string | Provider ID. |
$createdAt | string | Provider creation time (ISO 8601). |
$updatedAt | string | Provider update time (ISO 8601). |
name | string | Provider instance name. |
provider | string | Provider service identifier. |
enabled | boolean | Whether the provider is enabled. |
type | string | Provider channel type. |
credentials | object | Provider credentials; fields and response content vary by provider and deployment. |
options | object | Provider options. |
Call example:
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
}'Response excerpt (unrelated fields omitted):
{
"$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}
Update Resend provider (scope providers.write. SDK: Providers.updateResendProvider.)
Input (application/json)
| Parameter | Location | Type | Required | Default/enum | Description |
|---|---|---|---|---|---|
name | body | string | No | — | Provider name. |
enabled | body | boolean | No | Can be null | Whether enabled. |
apiKey | body | string | No | — | Resend API key. |
fromName | body | string | No | — | Sender name. |
fromEmail | body | string | No | — | Sender email address. |
replyToName | body | string | No | — | Email Reply-To name. Defaults to the sender name. |
replyToEmail | body | string | No | — | Email Reply-To address. Defaults to the sender email address. |
providerId | path | string | Yes | — | Provider ID. |
Output: 200, model provider (full fields described above), key fields:
| Field | Type | Description |
|---|---|---|
$id | string | Provider ID. |
$createdAt | string | Provider creation time (ISO 8601). |
$updatedAt | string | Provider update time (ISO 8601). |
name | string | Provider instance name. |
provider | string | Provider service identifier. |
enabled | boolean | Whether the provider is enabled. |
type | string | Provider channel type. |
credentials | object | Provider credentials; fields and response content vary by provider and deployment. |
options | object | Provider options. |
Call example:
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"
}'Response excerpt (unrelated fields omitted):
{
"$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
Create SendGrid email provider (scope providers.write. SDK: Providers.createSendgridProvider.)
Input (application/json)
| Parameter | Location | Type | Required | Default/enum | Description |
|---|---|---|---|---|---|
providerId | body | string | Yes | — | Provider ID. Can be customized, or generated with the SDK's ID.unique(); only a-z, A-Z, 0-9, periods, hyphens, and underscores are allowed, and it cannot start with a special character. At most 36 characters. |
name | body | string | Yes | — | Provider name. |
apiKey | body | string | No | — | SendGrid API key. |
fromName | body | string | No | — | Sender name. |
fromEmail | body | string | No | — | Sender email address. |
replyToName | body | string | No | — | Email Reply-To name. Defaults to the sender name. |
replyToEmail | body | string | No | — | Email Reply-To address. Defaults to the sender email address. |
enabled | body | boolean | No | Can be null | Whether enabled. |
Output: 201, model provider (full fields described above), key fields:
| Field | Type | Description |
|---|---|---|
$id | string | Provider ID. |
$createdAt | string | Provider creation time (ISO 8601). |
$updatedAt | string | Provider update time (ISO 8601). |
name | string | Provider instance name. |
provider | string | Provider service identifier. |
enabled | boolean | Whether the provider is enabled. |
type | string | Provider channel type. |
credentials | object | Provider credentials; fields and response content vary by provider and deployment. |
options | object | Provider options. |
Call example:
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
}'Response excerpt (unrelated fields omitted):
{
"$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}
Update SendGrid provider (scope providers.write. SDK: Providers.updateSendgridProvider.)
Input (application/json)
| Parameter | Location | Type | Required | Default/enum | Description |
|---|---|---|---|---|---|
name | body | string | No | — | Provider name. |
enabled | body | boolean | No | Can be null | Whether enabled. |
apiKey | body | string | No | — | SendGrid API key. |
fromName | body | string | No | — | Sender name. |
fromEmail | body | string | No | — | Sender email address. |
replyToName | body | string | No | — | Email Reply-To name. Defaults to the sender name. |
replyToEmail | body | string | No | — | Email Reply-To address. Defaults to the sender email address. |
providerId | path | string | Yes | — | Provider ID. |
Output: 200, model provider (full fields described above), key fields:
| Field | Type | Description |
|---|---|---|
$id | string | Provider ID. |
$createdAt | string | Provider creation time (ISO 8601). |
$updatedAt | string | Provider update time (ISO 8601). |
name | string | Provider instance name. |
provider | string | Provider service identifier. |
enabled | boolean | Whether the provider is enabled. |
type | string | Provider channel type. |
credentials | object | Provider credentials; fields and response content vary by provider and deployment. |
options | object | Provider options. |
Call example:
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"
}'Response excerpt (unrelated fields omitted):
{
"$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
Create a generic SMTP email provider: host, port, encryption method, and auth credentials. This endpoint is marked as deprecated in the spec (still available in v2.6.0; the SDK keeps the corresponding method). (Scope providers.write. SDK: Providers.createSmtpProvider.)
Input (application/json)
| Parameter | Location | Type | Required | Default/enum | Description |
|---|---|---|---|---|---|
providerId | body | string | Yes | — | Provider ID. Can be customized, or generated with the SDK's ID.unique(); only a-z, A-Z, 0-9, periods, hyphens, and underscores are allowed, and it cannot start with a special character. At most 36 characters. |
name | body | string | Yes | — | Provider name. |
host | body | string | Yes | — | 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 | No | — | SMTP port. |
username | body | string | No | — | Auth username. |
password | body | string | No | — | Auth password. |
encryption | body | string | No | none / ssl / tls | Encryption method: none (no encryption) / ssl / tls. |
autoTLS | body | boolean | No | — | Whether to enable SMTP AutoTLS. |
mailer | body | string | No | — | Value of the X-Mailer header. |
fromName | body | string | No | — | Sender name. |
fromEmail | body | string | No | — | Sender email address. |
replyToName | body | string | No | — | Email Reply-To name. Defaults to the sender name. |
replyToEmail | body | string | No | — | Email Reply-To address. Defaults to the sender email address. |
enabled | body | boolean | No | Can be null | Whether enabled. |
Output: 201, model provider (full fields described above), key fields:
| Field | Type | Description |
|---|---|---|
$id | string | Provider ID. |
$createdAt | string | Provider creation time (ISO 8601). |
$updatedAt | string | Provider update time (ISO 8601). |
name | string | Provider instance name. |
provider | string | Provider service identifier. |
enabled | boolean | Whether the provider is enabled. |
type | string | Provider channel type. |
credentials | object | Provider credentials; fields and response content vary by provider and deployment. |
options | object | Provider options. |
Call example:
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"
}'Response excerpt (unrelated fields omitted):
{
"$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}
Update SMTP provider. This endpoint is marked as deprecated in the spec (still available in v2.6.0; the SDK keeps the corresponding method). (Scope providers.write. SDK: Providers.updateSmtpProvider.)
Input (application/json)
| Parameter | Location | Type | Required | Default/enum | Description |
|---|---|---|---|---|---|
name | body | string | No | — | Provider name. |
host | body | string | No | — | 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 | No | Can be null | SMTP port. |
username | body | string | No | — | Auth username. |
password | body | string | No | — | Auth password. |
encryption | body | string | No | none / ssl / tls | Encryption method: ssl / tls. |
autoTLS | body | boolean | No | Can be null | Whether to enable SMTP AutoTLS. |
mailer | body | string | No | — | Value of the X-Mailer header. |
fromName | body | string | No | — | Sender name. |
fromEmail | body | string | No | — | Sender email address. |
replyToName | body | string | No | — | Email Reply-To name. Defaults to the sender name. |
replyToEmail | body | string | No | — | Email Reply-To address. Defaults to the sender email address. |
enabled | body | boolean | No | Can be null | Whether enabled. |
providerId | path | string | Yes | — | Provider ID. |
Output: 200, model provider (full fields described above), key fields:
| Field | Type | Description |
|---|---|---|
$id | string | Provider ID. |
$createdAt | string | Provider creation time (ISO 8601). |
$updatedAt | string | Provider update time (ISO 8601). |
name | string | Provider instance name. |
provider | string | Provider service identifier. |
enabled | boolean | Whether the provider is enabled. |
type | string | Provider channel type. |
credentials | object | Provider credentials; fields and response content vary by provider and deployment. |
options | object | Provider options. |
Call example:
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"
}'Response excerpt (unrelated fields omitted):
{
"$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
Create Telesign SMS provider (scope providers.write. SDK: Providers.createTelesignProvider.)
Input (application/json)
| Parameter | Location | Type | Required | Default/enum | Description |
|---|---|---|---|---|---|
providerId | body | string | Yes | — | Provider ID. Can be customized, or generated with the SDK's ID.unique(); only a-z, A-Z, 0-9, periods, hyphens, and underscores are allowed, and it cannot start with a special character. At most 36 characters. |
name | body | string | Yes | — | Provider name. |
from | body | string | No | — | Sender phone number, must be an + prefix with country code, e.g. +16175551212. |
customerId | body | string | No | — | Telesign customer ID. |
apiKey | body | string | No | — | Telesign API key. |
enabled | body | boolean | No | Can be null | Whether enabled. |
Output: 201, model provider (full fields described above), key fields:
| Field | Type | Description |
|---|---|---|
$id | string | Provider ID. |
$createdAt | string | Provider creation time (ISO 8601). |
$updatedAt | string | Provider update time (ISO 8601). |
name | string | Provider instance name. |
provider | string | Provider service identifier. |
enabled | boolean | Whether the provider is enabled. |
type | string | Provider channel type. |
credentials | object | Provider credentials; fields and response content vary by provider and deployment. |
options | object | Provider options. |
Call example:
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
}'Response excerpt (unrelated fields omitted):
{
"$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}
Update Telesign provider (scope providers.write. SDK: Providers.updateTelesignProvider.)
Input (application/json)
| Parameter | Location | Type | Required | Default/enum | Description |
|---|---|---|---|---|---|
name | body | string | No | — | Provider name. |
enabled | body | boolean | No | Can be null | Whether enabled. |
customerId | body | string | No | — | Telesign customer ID. |
apiKey | body | string | No | — | Telesign API key. |
from | body | string | No | — | Sender phone number. |
providerId | path | string | Yes | — | Provider ID. |
Output: 200, model provider (full fields described above), key fields:
| Field | Type | Description |
|---|---|---|
$id | string | Provider ID. |
$createdAt | string | Provider creation time (ISO 8601). |
$updatedAt | string | Provider update time (ISO 8601). |
name | string | Provider instance name. |
provider | string | Provider service identifier. |
enabled | boolean | Whether the provider is enabled. |
type | string | Provider channel type. |
credentials | object | Provider credentials; fields and response content vary by provider and deployment. |
options | object | Provider options. |
Call example:
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"
}'Response excerpt (unrelated fields omitted):
{
"$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
Create Textmagic SMS provider (scope providers.write. SDK: Providers.createTextmagicProvider.)
Input (application/json)
| Parameter | Location | Type | Required | Default/enum | Description |
|---|---|---|---|---|---|
providerId | body | string | Yes | — | Provider ID. Can be customized, or generated with the SDK's ID.unique(); only a-z, A-Z, 0-9, periods, hyphens, and underscores are allowed, and it cannot start with a special character. At most 36 characters. |
name | body | string | Yes | — | Provider name. |
from | body | string | No | — | Sender phone number, must be an + prefix with country code, e.g. +16175551212. |
username | body | string | No | — | Textmagic username. |
apiKey | body | string | No | — | Textmagic API key. |
enabled | body | boolean | No | Can be null | Whether enabled. |
Output: 201, model provider (full fields described above), key fields:
| Field | Type | Description |
|---|---|---|
$id | string | Provider ID. |
$createdAt | string | Provider creation time (ISO 8601). |
$updatedAt | string | Provider update time (ISO 8601). |
name | string | Provider instance name. |
provider | string | Provider service identifier. |
enabled | boolean | Whether the provider is enabled. |
type | string | Provider channel type. |
credentials | object | Provider credentials; fields and response content vary by provider and deployment. |
options | object | Provider options. |
Call example:
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
}'Response excerpt (unrelated fields omitted):
{
"$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}
Update Textmagic provider (scope providers.write. SDK: Providers.updateTextmagicProvider.)
Input (application/json)
| Parameter | Location | Type | Required | Default/enum | Description |
|---|---|---|---|---|---|
name | body | string | No | — | Provider name. |
enabled | body | boolean | No | Can be null | Whether enabled. |
username | body | string | No | — | Textmagic username. |
apiKey | body | string | No | — | Textmagic API key. |
from | body | string | No | — | Sender phone number. |
providerId | path | string | Yes | — | Provider ID. |
Output: 200, model provider (full fields described above), key fields:
| Field | Type | Description |
|---|---|---|
$id | string | Provider ID. |
$createdAt | string | Provider creation time (ISO 8601). |
$updatedAt | string | Provider update time (ISO 8601). |
name | string | Provider instance name. |
provider | string | Provider service identifier. |
enabled | boolean | Whether the provider is enabled. |
type | string | Provider channel type. |
credentials | object | Provider credentials; fields and response content vary by provider and deployment. |
options | object | Provider options. |
Call example:
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"
}'Response excerpt (unrelated fields omitted):
{
"$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
Create Twilio SMS provider (scope providers.write. SDK: Providers.createTwilioProvider.)
Input (application/json)
| Parameter | Location | Type | Required | Default/enum | Description |
|---|---|---|---|---|---|
providerId | body | string | Yes | — | Provider ID. Can be customized, or generated with the SDK's ID.unique(); only a-z, A-Z, 0-9, periods, hyphens, and underscores are allowed, and it cannot start with a special character. At most 36 characters. |
name | body | string | Yes | — | Provider name. |
from | body | string | No | — | Sender phone number, must be an + prefix with country code, e.g. +16175551212. |
accountSid | body | string | No | — | Twilio Account SID. |
authToken | body | string | No | — | Twilio Auth Token. |
enabled | body | boolean | No | Can be null | Whether enabled. |
Output: 201, model provider (full fields described above), key fields:
| Field | Type | Description |
|---|---|---|
$id | string | Provider ID. |
$createdAt | string | Provider creation time (ISO 8601). |
$updatedAt | string | Provider update time (ISO 8601). |
name | string | Provider instance name. |
provider | string | Provider service identifier. |
enabled | boolean | Whether the provider is enabled. |
type | string | Provider channel type. |
credentials | object | Provider credentials; fields and response content vary by provider and deployment. |
options | object | Provider options. |
Call example:
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
}'Response excerpt (unrelated fields omitted):
{
"$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}
Update Twilio provider (scope providers.write. SDK: Providers.updateTwilioProvider.)
Input (application/json)
| Parameter | Location | Type | Required | Default/enum | Description |
|---|---|---|---|---|---|
name | body | string | No | — | Provider name. |
enabled | body | boolean | No | Can be null | Whether enabled. |
accountSid | body | string | No | — | Twilio Account SID. |
authToken | body | string | No | — | Twilio Auth Token. |
from | body | string | No | — | Sender phone number. |
providerId | path | string | Yes | — | Provider ID. |
Output: 200, model provider (full fields described above), key fields:
| Field | Type | Description |
|---|---|---|
$id | string | Provider ID. |
$createdAt | string | Provider creation time (ISO 8601). |
$updatedAt | string | Provider update time (ISO 8601). |
name | string | Provider instance name. |
provider | string | Provider service identifier. |
enabled | boolean | Whether the provider is enabled. |
type | string | Provider channel type. |
credentials | object | Provider credentials; fields and response content vary by provider and deployment. |
options | object | Provider options. |
Call example:
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"
}'Response excerpt (unrelated fields omitted):
{
"$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
Create Vonage SMS provider (scope providers.write. SDK: Providers.createVonageProvider.)
Input (application/json)
| Parameter | Location | Type | Required | Default/enum | Description |
|---|---|---|---|---|---|
providerId | body | string | Yes | — | Provider ID. Can be customized, or generated with the SDK's ID.unique(); only a-z, A-Z, 0-9, periods, hyphens, and underscores are allowed, and it cannot start with a special character. At most 36 characters. |
name | body | string | Yes | — | Provider name. |
from | body | string | No | — | Sender phone number, must be an + prefix with country code, e.g. +16175551212. |
apiKey | body | string | No | — | Vonage API key. |
apiSecret | body | string | No | — | Vonage API secret. |
enabled | body | boolean | No | Can be null | Whether enabled. |
Output: 201, model provider (full fields described above), key fields:
| Field | Type | Description |
|---|---|---|
$id | string | Provider ID. |
$createdAt | string | Provider creation time (ISO 8601). |
$updatedAt | string | Provider update time (ISO 8601). |
name | string | Provider instance name. |
provider | string | Provider service identifier. |
enabled | boolean | Whether the provider is enabled. |
type | string | Provider channel type. |
credentials | object | Provider credentials; fields and response content vary by provider and deployment. |
options | object | Provider options. |
Call example:
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
}'Response excerpt (unrelated fields omitted):
{
"$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}
Update Vonage provider (scope providers.write. SDK: Providers.updateVonageProvider.)
Input (application/json)
| Parameter | Location | Type | Required | Default/enum | Description |
|---|---|---|---|---|---|
name | body | string | No | — | Provider name. |
enabled | body | boolean | No | Can be null | Whether enabled. |
apiKey | body | string | No | — | Vonage API key. |
apiSecret | body | string | No | — | Vonage API secret. |
from | body | string | No | — | Sender phone number. |
providerId | path | string | Yes | — | Provider ID. |
Output: 200, model provider (full fields described above), key fields:
| Field | Type | Description |
|---|---|---|
$id | string | Provider ID. |
$createdAt | string | Provider creation time (ISO 8601). |
$updatedAt | string | Provider update time (ISO 8601). |
name | string | Provider instance name. |
provider | string | Provider service identifier. |
enabled | boolean | Whether the provider is enabled. |
type | string | Provider channel type. |
credentials | object | Provider credentials; fields and response content vary by provider and deployment. |
options | object | Provider options. |
Call example:
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"
}'Response excerpt (unrelated fields omitted):
{
"$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}
Read provider details by ID; responses may contain sensitive configuration and must be protected (scope providers.read. SDK: Providers.getProvider.)
Input
| Parameter | Location | Type | Required | Default/enum | Description |
|---|---|---|---|---|---|
providerId | path | string | Yes | — | Provider ID. |
Output: 200, model provider (full fields described above), key fields:
| Field | Type | Description |
|---|---|---|
$id | string | Provider ID. |
$createdAt | string | Provider creation time (ISO 8601). |
$updatedAt | string | Provider update time (ISO 8601). |
name | string | Provider instance name. |
provider | string | Provider service identifier. |
enabled | boolean | Whether the provider is enabled. |
type | string | Provider channel type. |
credentials | object | Provider credentials; fields and response content vary by provider and deployment. |
options | object | Provider options. |
Call example:
curl "https://<your-endpoint>/v1/messaging/providers/<PROVIDER_ID>" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>"Response excerpt:
{
"$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}
Delete provider: unsent messages will fail delivery due to the lack of an available provider (scope providers.write. SDK: Providers.deleteProvider.)
Input
| Parameter | Location | Type | Required | Default/enum | Description |
|---|---|---|---|---|---|
providerId | path | string | Yes | — | Provider ID. |
Output: 204 No response body.
Call example:
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>"Response example:
_Binary stream or no response body (see output description)._
GET /v1/messaging/providers/{providerId}/logs
List delivery logs for this provider (only limit/offset pagination is supported) (scope providers.read. SDK: Providers.listProviderLogs.)
Input
| Parameter | Location | Type | Required | Default/enum | Description |
|---|---|---|---|---|---|
providerId | path | string | Yes | — | Provider ID. |
queries | query | string[] | No | Defaults to [] | Array of query strings, generated by the SDK's Query constructor (in the form of limit(25), equal("name","x")); only the limit / offset methods are supported. |
total | query | boolean | No | Default true | When set to false, skips total count calculation and the returned total is fixed at 0. |
Output: 200, model logList: total (total number of matches, not calculated when total=false) + logs[] (current page of data).
Key fields of the element model log:
| Field | Type | Description |
|---|---|---|
event | string | Event name. |
userId | string | ID of the user who triggered this log. When impersonation is used, the impersonator is recorded rather than the impersonated user. |
userEmail | string | Email of the user who triggered this log. |
mode | string | API mode when the event was triggered (admin/key, etc.). |
ip | string | Source IP when the event occurred. |
time | string | Log creation time (ISO 8601). |
clientName | string | Client name. |
countryName | string | Country/region name. |
Call example:
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)"Response example:
{
"total": 5,
"logs": ""
}Topics and Subscribers
GET /v1/messaging/topics
List all topics in the project with pagination (scope topics.read. SDK: Topics.listTopics.)
Input
| Parameter | Location | Type | Required | Default/enum | Description |
|---|---|---|---|---|---|
queries | query | string[] | No | Default [] | Array of query strings generated by the SDK's Query constructor (e.g. limit(25), equal("name","x")); supports filtering, sorting, and pagination (limit / cursorAfter / cursorBefore); filterable attributes: name, description, emailTotal, smsTotal, pushTotal. Maximum of 100 queries, each up to 4096 characters long. |
search | query | string | No | — | Search term that fuzzily filters list results. Up to 256 characters. |
total | query | boolean | No | Default true | When set to false, skips total count calculation and the returned total is fixed at 0. |
Output: 200, model topicList: total (total number of matches, not calculated when total=false) + topics[] (current page of data).
Key fields of the element model topic:
| Field | Type | Description |
|---|---|---|
$id | string | Topic ID. |
$createdAt | string | Topic creation time (ISO 8601). |
$updatedAt | string | Topic update time (ISO 8601). |
name | string | Topic name. |
emailTotal | integer | Number of email targets subscribed to this topic. |
smsTotal | integer | Number of SMS targets subscribed to this topic. |
pushTotal | integer | Number of push targets subscribed to this topic. |
subscribe | string[] | Roles that can subscribe. |
Call example:
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"Response example:
{
"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
Create topic: subscribe controls which roles can subscribe (defaults to all users) (scope topics.write. SDK: Topics.createTopic.)
Input (application/json)
| Parameter | Location | Type | Required | Default/enum | Description |
|---|---|---|---|---|---|
topicId | body | string | Yes | — | Topic ID. A custom new ID can be provided. |
name | body | string | Yes | — | Topic name. |
subscribe | body | string[] | No | — | Array of roles that have subscribe permission. By default, all users can subscribe. Maximum of 100 roles, each up to 64 characters long. |
Output: 201, model topic, fields:
| Field | Type | Description |
|---|---|---|
$id | string | Topic ID. |
$createdAt | string | Topic creation time (ISO 8601). |
$updatedAt | string | Topic update time (ISO 8601). |
name | string | Topic name. |
emailTotal | integer | Number of email targets subscribed to this topic. |
smsTotal | integer | Number of SMS targets subscribed to this topic. |
pushTotal | integer | Number of push targets subscribed to this topic. |
subscribe | string[] | Roles that can subscribe. |
Call example:
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"
]
}'Response example:
{
"$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}
Read topic details and subscription counts per channel (scope topics.read. SDK: Topics.getTopic.)
Input
| Parameter | Location | Type | Required | Default/enum | Description |
|---|---|---|---|---|---|
topicId | path | string | Yes | — | Topic ID. |
Output: 200, model topic (full fields described above), key fields:
| Field | Type | Description |
|---|---|---|
$id | string | Topic ID. |
$createdAt | string | Topic creation time (ISO 8601). |
$updatedAt | string | Topic update time (ISO 8601). |
name | string | Topic name. |
emailTotal | integer | Number of email targets subscribed to this topic. |
smsTotal | integer | Number of SMS targets subscribed to this topic. |
pushTotal | integer | Number of push targets subscribed to this topic. |
subscribe | string[] | Roles that can subscribe. |
Call example:
curl "https://<your-endpoint>/v1/messaging/topics/<TOPIC_ID>" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>"Response example:
{
"$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}
Update topic name and subscribable roles (scope topics.write. SDK: Topics.updateTopic.)
Input (application/json)
| Parameter | Location | Type | Required | Default/enum | Description |
|---|---|---|---|---|---|
name | body | string | No | Can be null | Topic name. |
subscribe | body | string[] | No | Can be null | Array of roles that have subscribe permission. By default, all users can subscribe. Maximum of 100 roles, each up to 64 characters long. |
topicId | path | string | Yes | — | Topic ID. |
Output: 200, model topic (full fields described above), key fields:
| Field | Type | Description |
|---|---|---|
$id | string | Topic ID. |
$createdAt | string | Topic creation time (ISO 8601). |
$updatedAt | string | Topic update time (ISO 8601). |
name | string | Topic name. |
emailTotal | integer | Number of email targets subscribed to this topic. |
smsTotal | integer | Number of SMS targets subscribed to this topic. |
pushTotal | integer | Number of push targets subscribed to this topic. |
subscribe | string[] | Roles that can subscribe. |
Call example:
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"
]
}'Response example:
{
"$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}
Delete a topic and its subscriptions (scope topics.write. SDK: Topics.deleteTopic.)
Input
| Parameter | Location | Type | Required | Default/enum | Description |
|---|---|---|---|---|---|
topicId | path | string | Yes | — | Topic ID. |
Output: 204 No response body.
Call example:
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>"Response example:
_Binary stream or no response body (see output description)._
GET /v1/messaging/topics/{topicId}/logs
List delivery logs for this topic (only limit/offset pagination is supported) (scope topics.read. SDK: Topics.listTopicLogs.)
Input
| Parameter | Location | Type | Required | Default/enum | Description |
|---|---|---|---|---|---|
topicId | path | string | Yes | — | Topic ID. |
queries | query | string[] | No | Defaults to [] | Array of query strings, generated by the SDK's Query constructor (in the form of limit(25), equal("name","x")); only the limit / offset methods are supported. |
total | query | boolean | No | Default true | When set to false, skips total count calculation and the returned total is fixed at 0. |
Output: 200, model logList: total (total number of matches, not calculated when total=false) + logs[] (current page of data).
Key fields of the element model log:
| Field | Type | Description |
|---|---|---|
event | string | Event name. |
userId | string | ID of the user who triggered this log. When impersonation is used, the impersonator is recorded rather than the impersonated user. |
userEmail | string | Email of the user who triggered this log. |
mode | string | API mode when the event was triggered (admin/key, etc.). |
ip | string | Source IP when the event occurred. |
time | string | Log creation time (ISO 8601). |
clientName | string | Client name. |
countryName | string | Country/region name. |
Call example:
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)"Response example:
{
"total": 5,
"logs": ""
}GET /v1/messaging/topics/{topicId}/subscribers
Paginate through subscribers of a topic (scope subscribers.read. SDK: Subscribers.listSubscribers.)
Input
| Parameter | Location | Type | Required | Default/enum | Description |
|---|---|---|---|---|---|
topicId | path | string | Yes | — | ID of the topic to subscribe to. |
queries | query | string[] | No | Defaults to [] | Array of query strings, generated by the SDK's Query constructor (in the form of limit(25), equal("name","x")); supports filtering, sorting, and pagination (limit / cursorAfter / cursorBefore); filterable attributes: targetId, topicId, userId, providerType. At most 100 queries, each at most 4096 characters. |
search | query | string | No | — | Search term that fuzzily filters list results. Up to 256 characters. |
total | query | boolean | No | Default true | When set to false, skips total count calculation and the returned total is fixed at 0. |
Output: 200, model subscriberList: total (total number of matches, not calculated when total=false) + subscribers[] (current page of data).
Key fields of the element model subscriber:
| Field | Type | Description |
|---|---|---|
$id | string | Subscriber ID. |
$createdAt | string | Subscription creation time (ISO 8601). |
$updatedAt | string | Subscription update time (ISO 8601). |
targetId | string | Target ID. |
target | object | Message target object. |
topicId | string | Topic ID. |
Call example:
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"Response example:
{
"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
Create a topic subscription for a target: the targetId must belong to a message target of an existing user (scope subscribers.write. SDK: Subscribers.createSubscriber.)
Input (application/json)
| Parameter | Location | Type | Required | Default/enum | Description |
|---|---|---|---|---|---|
subscriberId | body | string | Yes | — | Subscriber ID. A new custom ID can be provided. |
targetId | body | string | Yes | — | Target ID to associate with the topic (a message target from users). |
topicId | path | string | Yes | — | ID of the topic to subscribe to. |
Output: 201, model subscriber, fields:
| Field | Type | Description |
|---|---|---|
$id | string | Subscriber ID. |
$createdAt | string | Subscription creation time (ISO 8601). |
$updatedAt | string | Subscription update time (ISO 8601). |
targetId | string | Target ID. |
target | object | Message target object. |
userId | string | User ID associated with the subscriber. |
userName | string | Username associated with the subscriber. |
topicId | string | Topic ID. |
providerType | string | Target channel type: email / sms / push. |
Call example:
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"
}'Response example:
{
"$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}
Read a single subscription (scope subscribers.read. SDK: Subscribers.getSubscriber.)
Input
| Parameter | Location | Type | Required | Default/enum | Description |
|---|---|---|---|---|---|
topicId | path | string | Yes | — | ID of the topic to subscribe to. |
subscriberId | path | string | Yes | — | Subscriber ID. |
Output: 200, model subscriber (full fields described above), key fields:
| Field | Type | Description |
|---|---|---|
$id | string | Subscriber ID. |
$createdAt | string | Subscription creation time (ISO 8601). |
$updatedAt | string | Subscription update time (ISO 8601). |
targetId | string | Target ID. |
target | object | Message target object. |
topicId | string | Topic ID. |
Call example:
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>"Response example:
{
"$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}
Unsubscribe: delete the subscription (scope subscribers.write. SDK: Subscribers.deleteSubscriber.)
Input
| Parameter | Location | Type | Required | Default/enum | Description |
|---|---|---|---|---|---|
topicId | path | string | Yes | — | ID of the topic to subscribe to. |
subscriberId | path | string | Yes | — | Subscriber ID. |
Output: 204 No response body.
Call example:
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>"Response example:
_Binary stream or no response body (see output description)._
GET /v1/messaging/subscribers/{subscriberId}/logs
List delivery logs for this subscriber (only limit/offset pagination is supported) (scope subscribers.read. SDK: Subscribers.listSubscriberLogs.)
Input
| Parameter | Location | Type | Required | Default/enum | Description |
|---|---|---|---|---|---|
subscriberId | path | string | Yes | — | Subscriber ID. |
queries | query | string[] | No | Defaults to [] | Array of query strings, generated by the SDK's Query constructor (in the form of limit(25), equal("name","x")); only the limit / offset methods are supported. |
total | query | boolean | No | Default true | When set to false, skips total count calculation and the returned total is fixed at 0. |
Output: 200, model logList: total (total number of matches, not calculated when total=false) + logs[] (current page of data).
Key fields of the element model log:
| Field | Type | Description |
|---|---|---|
event | string | Event name. |
userId | string | ID of the user who triggered this log. When impersonation is used, the impersonator is recorded rather than the impersonated user. |
userEmail | string | Email of the user who triggered this log. |
mode | string | API mode when the event was triggered (admin/key, etc.). |
ip | string | Source IP when the event occurred. |
time | string | Log creation time (ISO 8601). |
clientName | string | Client name. |
countryName | string | Country/region name. |
Call example:
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)"Response example:
{
"total": 5,
"logs": ""
}Errors and boundaries
Message/provider/topic/subscriber not found:
404+message_not_found/provider_not_found/topic_not_found/subscriber_not_found; duplicate provider:provider_already_exists.Delivery failure: message
status=failed, failure details indeliveryDataand message logs; scheduled messages can be modified or deleted before sending.Attachments and images must be
<BUCKET_ID>:<FILE_ID>composite IDs and the files must exist in Storage; pushimageonly accepts jpeg/png.If no provider is configured for the corresponding channel, the message will be created successfully but delivery will fail—create the provider before sending the message.
SMS/email are billed per provider; before mass sending, verify with
draft+ a small-scaletargets;scheduledAtmust be a future time, accurate to the minute.
Correspondence with the Server SDK
| service.method | Endpoint |
|---|---|
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 types), 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 |