Skip to main content

Notification Channels & Preferences

Beyond webhooks, the platform can notify you by email and through an in-app inbox. Preferences control which events reach which channel.

Email recipients​

POST   /notifications/email-configs                     add an address
GET    /notifications/email-configs                     list
GET    /notifications/email-configs/{config_id}         detail
PUT    /notifications/email-configs/{config_id}         enable/disable
DELETE /notifications/email-configs/{config_id}         remove (204)
GET    /notifications/email-configs/{config_id}/deliveries   delivery history

Maximum 5 addresses per account, and each must be unique — exceeding either returns 400.

An email config says where mail goes, not what is sent: it carries no event list. Which events produce mail is decided entirely by preferences.

Like webhooks, repeated delivery failures disable an address automatically.

In-app inbox​

GET    /notifications/in-app                        list (page_size default 20, unread_only)
GET    /notifications/in-app/unread-count           badge count
PUT    /notifications/in-app/{notification_id}/read mark one read
PUT    /notifications/in-app/mark-all-read          mark all read
DELETE /notifications/in-app/{notification_id}      delete (204)
POST   /notifications/in-app/archive                bulk archive

Notifications are typed INFO, SUCCESS, WARNING, ERROR or ACTION_REQUIRED, point at a resource, and expire after 30 days.

Two quirks worth knowing: the list envelope carries an extra unread_count field beyond the standard pagination shape, and this endpoint always returns 200 with an empty array rather than a 204.

Preferences​

GET  /notifications/preferences
PUT  /notifications/preferences
POST /notifications/preferences/reset

Three levels, most specific winning: global → category → event.

global_preferences   { email_enabled, in_app_enabled, push_enabled, frequency }
category_preferences { "<category>": { enabled, channels[] } }
event_preferences    { "<event.type>": { enabled, channels[] } }

Categories are derived from the event name: vault_notifications, stream_notifications, data_attachment_notifications, signature_notifications, asset_notifications, permission_notifications, security_notifications.

warning

A disabled category short-circuits. Turning off vault_notifications suppresses every vault event regardless of any event-level override beneath it. Globals cap categories the same way. Work top-down when debugging a notification that never arrived.

note

signature_notifications and asset_notifications are not present in the default preference set. Signature and asset events therefore fall through to your global settings until you create those keys explicitly.

Webhooks ignore all of this​

Webhook delivery is never gated by preferences — disabling everything globally still leaves WEBHOOK enabled. To stop webhook deliveries, disable or delete the webhook configuration itself.

Deduplication applies to every channel​

The same 5-minute deduplication window described for webhooks applies across email and in-app too, and it is keyed on the in-app notification record. Deleting in-app notifications, or disabling that channel, changes deduplication behaviour for the others.

Not available on this API​

  • Push notifications. push_enabled is settable in preferences, but there is no device-token endpoint on the partner API — device registration exists only in the mobile application. Enabling push here has no effect for an API integration.
  • frequency: DAILY_DIGEST. The value is stored and returned, but nothing consumes it. All delivery is real-time. Do not build against it.