Messaging
Overview and use cases
Messaging surface: Provider (channel credentials) → Topic (subscription topic) / Subscriber (subscriber) → Message (Email / Push / SMS, supporting drafts and scheduled sending), plus send / channel / subscription logs. Use cases: announcements and notifications (email / SMS / app push), topic-based bulk sending, scheduled delivery.
Prerequisites
Server API Key:
messaging.read/messaging.write。Configure at least one usable Provider (Email requires instance SMTP or a third-party email channel; Push requires APNs / FCM credentials; SMS requires Twilio / Telesign / Vonage / Textmagic, etc.).
Recipient model: at least one of
topics(topic subscription),users(user ID), ortargets(user push target / email / phone number).
Usage workflow
Configure a Provider: choose the creation method by channel —
createApnsProvider/createFcmProvider(Push),createMailgunProvider/createResendProvider/createSendgridProvider/createSmtpProvider(Email),createTwilioProvider/createTelesignProvider/createVonageProvider/createTextmagicProvider(SMS), all withupdate*Provider/getProvider/listProviders/deleteProvider; verify credential fields against the corresponding Provider documentation; responses may contain sensitive configuration; avoid logging or exposing it.Create a Topic:
messaging.createTopic({ topicId, name, subscribeUsers })(subscribeUsersoptional) (enable when subscription requires user authorization);listTopics/getTopic/updateTopic/deleteTopic.Subscribers:
messaging.createSubscriber({ topicId, subscriberId, targetId });listSubscribers/getSubscriber/deleteSubscriber.Create a message: choose by channel —
createEmail({ messageId, subject, content, topics, users, targets, cc, bcc, attachments, draft, html, scheduledAt })(topics,users,targets,cc,bcc,attachments,draft,html,scheduledAtall optional)createPush({ messageId, title, body, ... , topics, users, targets, draft, scheduledAt })(title,body,topics,users,targets,draft,scheduledAtall optional)createSms({ messageId, content, ... , draft, scheduledAt })(draft,scheduledAtboth optional)All have
updateEmail/updatePush/updateSmsandgetMessage/listMessages/delete.
Drafts and scheduling:
draft: trueonly saves without sending (draft state, can be updated repeatedly);scheduledAtwith a future ISO 8601 time schedules sending; the two can be combined (draft + future send time). The platform delivers at the scheduled time; the caller does not need to poll to trigger it.Logs and troubleshooting:
listMessageLogs(delivery status;scheduledAt/deliveredAt/deliveredTotal/statuscan be used as query filter attributes),listTopicLogs/listSubscriberLogs/listProviderLogs;messaging.listTargetsto look up a user's push targets.
Key parameters and returns
| Call | Key parameters | Returns |
|---|---|---|
createTopic | topicId, name, subscribeUsers (optional; whether user authorization is required to subscribe) | Models.Topic |
createSubscriber | topicId、subscriberId、targetId | Models.Subscriber |
createEmail | messageId, subject, content, topics / users / targets (all optional), cc / bcc / attachments (all optional), draft (optional), html (optional), scheduledAt (optional) | Models.Message (including status, scheduledAt, deliveredTotal) |
createPush / createSms | content fields, delivery targets, messageId (optional), draft (optional), scheduledAt (optional) | Models.Message |
create*Provider | Channel credentials (providerId, name, auth fields, enabled, etc.) | Provider (response may contain sensitive configuration) |
Message queries support filtering by the scheduledAt, deliveredAt, deliveredTotal, status, description, providerType attributes (queries limit 100 records).
Errors and boundaries
No usable Provider / credential error: messages stay pending delivery and the failure reason is recorded — first check
listMessageLogsand the Provider configuration.scheduledAtmust be a future time; use theupdate*Messageseries of updates to modify the schedule for the samemessageId.Messages in
draft: truewill not be delivered; forgetting to change the draft state is the number-one cause of "why isn't it sending".The three delivery target types (topics / users / targets) can be combined;
targetspoints to the user's push targets (IDs inusers.createTargetormessaging.listTargets).Email attachments reference file IDs within the project; size and format are limited by the Provider and the instance.
When a subscription-type Topic enables
subscribeUsers, subscription operations require the target user's authorization chain (user Session or server-side proxy operation).
SDK Category Differences
Server SDK: the main body of this page (full management of Provider / Topic / Subscriber / Message + logs); Java has identical synchronous methods, Python has the same structure in snake_case.
Client SDK: does not provide message sending management; on the user side there is only push target registration (profile.md) and Realtime subscription (client-sdk/web.md).
Console SDK: Email / SMS templates and SMTP testing (
updateEmailTemplate,createSmtpTest, etc.) in project settings are control-plane configuration, with a different division of responsibilities from business sending.Entry point for differences: server-sdk/nodejs.md.
Examples by language
The following provides examples by language, item by item along the usage workflow; each card can switch languages (synced across the page).
Configure a Provider
The messaging surface is exposed only server-side; the Client SDK (Web) has no such capability surface, so this card omits the Web tab.
- Node.js (Server)
- Java
- Python
- Go
- REST (curl)
import { Client, Messaging, ID } from 'agentbase-node-sdk';
const messaging = new Messaging(client); // For client initialization, see server-sdk/nodejs.md
await messaging.createFcmProvider({
providerId: ID.unique(),
name: 'app-push',
serviceAccountJSON: { type: 'service_account', project_id: 'my-project' },
enabled: true
});
// Email:createMailgunProvider / createResendProvider / createSendgridProvider / createSmtpProvider
// SMS:createTwilioProvider / createTelesignProvider / createVonageProvider / createTextmagicProvider / createMsg91Provider
// Push additionally has createApnsProvider; all pair with update*Provider / getProvider / listProviders / deleteProvider
// responses may contain sensitive configuration; rotate credentials via update*Providerimport io.agentbase.ID;
import io.agentbase.services.Messaging;
Messaging messaging = new Messaging(client); // For client initialization, see server-sdk/java.md
messaging.createFcmProvider(ID.unique(), "app-push",
java.util.Map.of("type", "service_account", "project_id", "my-project"), // serviceAccountJSON
true); // enabled
// 11 types of create*Provider channels (apns / fcm / mailgun / msg91 / resend / sendgrid / smtp / telesign /
// textmagic / twilio / vonage), all provide update*Provider / getProvider / listProviders / deleteProvider
// (positional arguments); createSmtpProvider has one extra required host: (providerId, name, host, port, ...)
// responses may contain sensitive configuration; rotate credentials via update*Providerfrom agentbase.id import ID
from agentbase.services.messaging import Messaging
messaging = Messaging(client) # client initialization see server-sdk/python.md
messaging.create_fcm_provider(
provider_id=ID.unique(),
name='app-push',
service_account_json={'type': 'service_account', 'project_id': 'my-project'}, # FCM service account JSON
enabled=True)
# Email:create_mailgun_provider / create_resend_provider / create_sendgrid_provider / create_smtp_provider
# SMS:create_twilio_provider / create_telesign_provider / create_vonage_provider / create_textmagic_provider
# All come with update_*_provider / get_provider / list_providers / delete_provider; responses may contain sensitive configuration; avoid logging or exposing itmessaging := agentbase.NewMessaging(cl) // facade constructor; cl is a Client already loaded with an API Key
_, err := messaging.CreateFcmProvider(id.Unique(), "app-push",
messaging.WithCreateFcmProviderServiceAccountJSON(
map[string]interface{}{"type": "service_account", "project_id": "my-project"}),
messaging.WithCreateFcmProviderEnabled(true))
// Email:CreateMailgunProvider / CreateResendProvider / CreateSendgridProvider / CreateSmtpProvider
// SMS:CreateTwilioProvider / CreateTelesignProvider / CreateVonageProvider / CreateTextmagicProvider
// Each has Update*Provider / GetProvider / ListProviders / DeleteProvider; responses may contain sensitive configuration; avoid logging or exposing itcurl -sS -X POST "$APPBASE_ENDPOINT/messaging/providers/fcm" \
-H 'Content-Type: application/json' \
-H "X-Appwrite-Project: $APPBASE_PROJECT_ID" \
-H "X-Appwrite-Key: $APPBASE_API_KEY" \
-d '{"providerId":"app-push","name":"App Push","serviceAccountJSON":{"type":"service_account","project_id":"my-project"},"enabled":true}'
# Other channels: POST /messaging/providers/{apns|mailgun|resend|sendgrid|smtp|twilio|vonage|telesign|msg91|textmagic}
# Update: PATCH /messaging/providers/{type}/{providerId} (fields not provided keep current values); responses may contain sensitive configuration; avoid logging or exposing it
# Deleting a provider causes unsent messages to fail delivery: DELETE /messaging/providers/{providerId}Create a Topic
subscribe controls which roles can subscribe (defaults to all users); the Client SDK (Web) has no such capability surface, so this card omits the Web tab.
- Node.js (Server)
- Java
- Python
- Go
- REST (curl)
const topic = await messaging.createTopic({
topicId: ID.unique(),
name: 'product-announcements',
subscribe: ['users'] // An array of roles can be subscribed, up to 100
});
await messaging.listTopics();
await messaging.getTopic(topic.$id);
// updateTopic: adjust the name and subscribable roles; deleteTopic: delete the topic and cascade-delete subscriptionsimport io.agentbase.ID;
import io.agentbase.services.Messaging;
Messaging messaging = new Messaging(client); // For client initialization, see server-sdk/java.md
var topic = messaging.createTopic(ID.unique(), "product-announcements",
java.util.List.of("users")); // An array of roles can be subscribed, up to 100
messaging.listTopics(null, null, null); // queries / search / total
messaging.getTopic(topic.getId());
// updateTopic(topicId, name, subscribe): adjust the name and subscribable roles
// deleteTopic(topicId): deletes the topic and cascades to delete subscriptionsmessaging = Messaging(client) # client initialization see server-sdk/python.md
topic = messaging.create_topic(topic_id=ID.unique(), name='product-announcements',
subscribe=['users']) # An array of roles can be subscribed, up to 100
messaging.list_topics()
messaging.get_topic(topic['$id'])
# update_topic: adjust the name and subscribable roles; delete_topic: delete the topic and cascade-delete subscriptionstopic, err := messaging.CreateTopic(id.Unique(), "product-announcements",
messaging.WithCreateTopicSubscribe([]string{"users"})) // An array of roles can be subscribed, up to 100
_, err = messaging.ListTopics()
_, err = messaging.GetTopic(topic.Id)
// UpdateTopic: adjust name and subscribable roles; DeleteTopic: delete the topic and cascade-delete subscriptionscurl -sS -X POST "$APPBASE_ENDPOINT/messaging/topics" \
-H 'Content-Type: application/json' \
-H "X-Appwrite-Project: $APPBASE_PROJECT_ID" \
-H "X-Appwrite-Key: $APPBASE_API_KEY" \
-d '{"topicId":"product-announcements","name":"Product Announcements","subscribe":["users"]}'
# List (filterable by name / description / emailTotal / smsTotal / pushTotal): GET /messaging/topics
# Update: PATCH /messaging/topics/{topicId} (name + subscribe); delete (cascades to subscriptions): DELETE /messaging/topics/{topicId}Subscribers
targetId must come from an existing user's message targets; the Client SDK (Web) has no such capability surface, so this card omits the Web tab.
- Node.js (Server)
- Java
- Python
- Go
- REST (curl)
const subscriber = await messaging.createSubscriber({
topicId: topic.$id,
subscriberId: ID.unique(),
targetId: '<targetId>' // The user's message target (users.createTarget or messaging.listTargets)
});
await messaging.listSubscribers(topic.$id);
await messaging.getSubscriber(topic.$id, subscriber.$id);
await messaging.deleteSubscriber(topic.$id, subscriber.$id); // Unsubscribevar subscriber = messaging.createSubscriber(topic.getId(), ID.unique(),
"<targetId>"); // The user's message target (users.createTarget or messaging.listTargets)
messaging.listSubscribers(topic.getId(), null, null, null); // queries / search / total
messaging.getSubscriber(topic.getId(), subscriber.getId());
messaging.deleteSubscriber(topic.getId(), subscriber.getId()); // Unsubscribesubscriber = messaging.create_subscriber(
topic_id=topic['$id'],
subscriber_id=ID.unique(),
target_id='<targetId>') # The user's message target (users.create_target or messaging.list_targets)
messaging.list_subscribers(topic_id=topic['$id'])
messaging.get_subscriber(topic_id=topic['$id'], subscriber_id=subscriber['$id'])
messaging.delete_subscriber(topic_id=topic['$id'], subscriber_id=subscriber['$id']) # Unsubscribesubscriber, err := messaging.CreateSubscriber(topic.Id, id.Unique(), "<targetId>") // targetId: the message's target user
_, err = messaging.ListSubscribers(topic.Id)
_, err = messaging.GetSubscriber(topic.Id, subscriber.Id)
_, err = messaging.DeleteSubscriber(topic.Id, subscriber.Id) // Unsubscribecurl -sS -X POST "$APPBASE_ENDPOINT/messaging/topics/product-announcements/subscribers" \
-H 'Content-Type: application/json' \
-H "X-Appwrite-Project: $APPBASE_PROJECT_ID" \
-H "X-Appwrite-Key: $APPBASE_API_KEY" \
-d '{"subscriberId":"sub-001","targetId":"66f1a2b3c4d5e6f7"}'
# List: GET /messaging/topics/{topicId}/subscribers; single item: GET …/subscribers/{subscriberId}
# Unsubscribe: DELETE /messaging/topics/{topicId}/subscribers/{subscriberId}Create a message (drafts and scheduling)
draft: true only saves without delivering and can be updated repeatedly before sending; scheduledAt with a future ISO 8601 time schedules delivery, and the platform delivers at that time. The Client SDK (Web) has no such capability surface, so this card omits the Web tab.
- Node.js (Server)
- Java
- Python
- Go
- REST (curl)
const message = await messaging.createEmail({
messageId: ID.unique(),
subject: '10 月产品更新',
content: '<h1>10 月产品更新</h1>',
html: true,
topics: [topic.$id], // Delivery targets topics / users / targets are composable
draft: false, // true only stores the draft without delivering it
scheduledAt: '2026-10-01T09:00:00.000+00:00' // A future time means scheduled sending
});
console.log(message.status, message.deliveredTotal);
// Push: createPush (title / body / data / action / badge / priority etc., effective per Android / iOS / Web platform)
// SMS: createSms (content); both have update*Message (only editable in draft state) and getMessage / listMessages / deletevar message = messaging.createEmail(ID.unique(), "10 月产品更新", "<h1>10 月产品更新</h1>",
java.util.List.of(topic.getId()), // topics; delivery targets topics / users / targets can be combined
null, null, null, null, null, // users / targets / cc / bcc / attachments
false, true, // draft (true saves as draft only without delivering), html
"2026-10-01T09:00:00.000+00:00"); // scheduledAt: a future time schedules the send
System.out.println(message.getStatus() + " " + message.getDeliveredTotal());
// Push: createPush(messageId, title, body, topics, …, badge, draft, scheduledAt, …) all-positional parameters, pass optionally
// SMS: createSms(messageId, content, …); both have updateEmail / updatePush / updateSms (only editable in draft state)
// Along with getMessage / listMessages / deletemessage = messaging.create_email(
message_id=ID.unique(),
subject='10 月产品更新',
content='<h1>10 月产品更新</h1>',
html=True,
topics=[topic['$id']], # Delivery targets topics / users / targets are composable
draft=False, # True stores as draft only without delivering
scheduled_at='2026-10-01T09:00:00+00:00') # A future time means scheduled sending
print(message.status) # scheduledAt / deliveredTotal can be checked via the returned model
# Push: create_push (title / body / data / action / badge / priority etc., applied per Android / iOS / Web platform)
# SMS: create_sms (content); both have update_email / update_push / update_sms (only editable in draft state) and
# get_message / list_messages / deletemessage, err := messaging.CreateEmail(id.Unique(), "10 月产品更新", "<h1>10 月产品更新</h1>",
messaging.WithCreateEmailHtml(true),
messaging.WithCreateEmailTopics([]string{topic.Id}), // Delivery targets topics / users / targets are composable
messaging.WithCreateEmailDraft(false), // true only stores the draft without delivering it
messaging.WithCreateEmailScheduledAt("2026-10-01T09:00:00.000+00:00")) // A future time means scheduled sending
// message.Status / ScheduledAt / DeliveredTotal can be checked via the returned model
// Push: CreatePush (title / body / data / action / badge / priority etc., effective per Android / iOS / Web platform)
// SMS: CreateSms (content); both have UpdateEmail / UpdatePush / UpdateSms (only editable in draft state) and
// GetMessage / ListMessages / Deletecurl -sS -X POST "$APPBASE_ENDPOINT/messaging/messages/email" \
-H 'Content-Type: application/json' \
-H "X-Appwrite-Project: $APPBASE_PROJECT_ID" \
-H "X-Appwrite-Key: $APPBASE_API_KEY" \
-d '{"messageId":"oct-newsletter","subject":"10 月产品更新","content":"<h1>10 月产品更新</h1>","html":true,"topics":["product-announcements"],"draft":false,"scheduledAt":"2026-10-01T09:00:00.000+00:00"}'
# Attachment is a composite ID: attachments:["<BUCKET_ID>:<FILE_ID>"] (the file must already be uploaded to Storage)
# Push / SMS: POST /messaging/messages/push, /messaging/messages/sms (the sms endpoint spec is marked deprecated, 2.6.0 still works)
# Update: only editable in draft state: PATCH /messaging/messages/email/{messageId}Logs and troubleshooting
Delivery status and failure reasons are investigated via message logs and deliveryErrors; the Client SDK (Web) has no such capability surface, so this card omits the Web tab.
- Node.js (Server)
- Java
- Python
- Go
- REST (curl)
const logs = await messaging.listMessageLogs(message.$id); // Delivery logs
const targets = await messaging.listTargets(message.$id); // recipient targets resolved from topics / users / targets
// status / scheduledAt / deliveredAt / deliveredTotal can be used as query filter attributes for messages
// Channel-side logs: listTopicLogs / listSubscriberLogs / listProviderLogsmessaging.listMessageLogs(message.getId(), null, null); // Delivery log; queries / total
messaging.listTargets(message.getId(), null, null); // recipient targets resolved from topics / users / targets
// status / scheduledAt / deliveredAt / deliveredTotal can be used as query filter attributes for messages
// Channel-side logs: listTopicLogs(topicId, queries, total) / listSubscriberLogs(subscriberId, queries, total)
// / listProviderLogs(providerId, queries, total)messaging.list_message_logs(message_id=message['$id']) # Delivery logs
messaging.list_targets(message_id=message['$id']) # recipient targets resolved from topics / users / targets
# status / scheduledAt / deliveredAt / deliveredTotal can be used as query filter attributes for messages
# Channel-side logs: list_topic_logs / list_subscriber_logs / list_provider_logs_, err := messaging.ListMessageLogs(message.Id) // Delivery logs
_, err = messaging.ListTargets(message.Id) // recipient targets resolved from topics / users / targets
// status / scheduledAt / deliveredAt / deliveredTotal can be used as query filter attributes for messages
// Channel-side logs: ListTopicLogs / ListSubscriberLogs / ListProviderLogscurl -sS -G "$APPBASE_ENDPOINT/messaging/messages/oct-newsletter/logs" \
-H "X-Appwrite-Project: $APPBASE_PROJECT_ID" -H "X-Appwrite-Key: $APPBASE_API_KEY" \
--data-urlencode "queries[]=limit(25)"
# Resolved recipient targets: GET /messaging/messages/{messageId}/targets
# Topic / subscriber / provider logs: GET /messaging/topics/{topicId}/logs, /messaging/subscribers/{subscriberId}/logs, /messaging/providers/{providerId}/logs (limit / offset pagination only)
# Message stuck in pending delivery? Check the channel first: GET /messaging/providersExample Guide
Usage in each language is gathered in the language tree
examples/; for the Provider type list and module overview seeskills/ob-agentbase/references/server-sdks/java.mdandskills/ob-agentbase/references/server-sdks/nodejs.md.