Notification Settings

Get and update workspace notification preferences. Preferences are per-user and control which events trigger email and push notifications, dormant account reminders, and marketing email opt-in.

Base URL


https://api.voxburst.io/v1/settings/notifications

Authentication: All endpoints require a Bearer token.


Authorization: Bearer eyJexample...

Get Notification Preferences

GET /v1/settings/notifications

Returns the current user’s notification preferences. If no preferences have been saved, the response returns platform defaults and isDefault: true — no record is created.


curl https://api.voxburst.io/v1/settings/notifications \
  -H "Authorization: Bearer eyJexample..."

Response (200)


{
  "preferences": {
    "emailEnabled": true,
    "pushEnabled": false,
    "postPublished": true,
    "postFailed": true,
    "weeklyDigest": false,
    "analyticsReport": false,
    "webhookFailed": true,
    "approvalUpdates": true,
    "timezone": "America/Chicago",
    "dormantLastPublishedEnabled": false,
    "dormantLastPublishedDays": 14,
    "dormantNoScheduledEnabled": false,
    "dormantNoScheduledDays": 7,
    "dormantWatchedAccountIds": [],
    "marketingEmails": true
  },
  "isDefault": true
}

isDefault: true indicates no preferences have been explicitly saved yet — these are the platform defaults. Once preferences are saved via PUT, isDefault is false in subsequent GET responses.

Update Notification Preferences

PUT /v1/settings/notifications

Updates the current user’s notification preferences. Creates the record if it does not exist. All fields are optional — send only the fields you want to change.


curl -X PUT https://api.voxburst.io/v1/settings/notifications \
  -H "Authorization: Bearer eyJexample..." \
  -H "Content-Type: application/json" \
  -d '{
    "webhookFailed": true,
    "approvalUpdates": true,
    "weeklyDigest": true
  }'

Response (200)


{
  "preferences": {
    "emailEnabled": true,
    "pushEnabled": false,
    "postPublished": true,
    "postFailed": true,
    "weeklyDigest": true,
    "analyticsReport": false,
    "webhookFailed": true,
    "approvalUpdates": true,
    "timezone": "America/Chicago",
    "dormantLastPublishedEnabled": false,
    "dormantLastPublishedDays": 14,
    "dormantNoScheduledEnabled": false,
    "dormantNoScheduledDays": 7,
    "dormantWatchedAccountIds": [],
    "marketingEmails": true
  },
  "message": "Preferences saved successfully"
}

The response returns the full saved preferences object. Fields not included in the request body retain their previous values.

Preference Fields

All fields apply to both the GET response (preferences object) and the PUT request body (all optional).

Notification Channels

Field	Type	Default	Description
`emailEnabled`	boolean	`true`	Master toggle for all email notifications. When `false`, no notification emails are sent regardless of individual event settings.
`pushEnabled`	boolean	`false`	Push notifications are not yet supported. This field is always returned as `false` and any value sent in a PUT request is ignored — the server forces it to `false`.

Event Notifications

Field	Type	Default	Description
`postPublished`	boolean	`true`	Send a notification when a scheduled post publishes successfully.
`postFailed`	boolean	`true`	Send a notification when a post fails to publish.
`weeklyDigest`	boolean	`false`	Send a weekly performance summary email.
`analyticsReport`	boolean	`false`	Send a periodic analytics report email.
`webhookFailed`	boolean	`true`	Send a notification when a webhook endpoint fails or is automatically disabled due to repeated delivery failures. Added 2026-06-15.
`approvalUpdates`	boolean	`true`	Send a notification when an approval workflow state changes: when a post is submitted for review, approved, or rejected. Added 2026-06-15.

For API consumers and automation workflows: webhookFailed and approvalUpdates are particularly relevant for integration scenarios.

webhookFailed ensures your team is alerted when a configured webhook endpoint goes down or begins failing. VoxBurst auto-disables endpoints after repeated failures — enabling this notification gives you early warning before the endpoint is disabled and event delivery stops.

approvalUpdates lets all participants in an approval workflow stay informed as posts move through review states. In multi-user workspaces using the approval workflow, this preference controls whether workspace members receive notifications at each state transition.

General Settings

Field	Type	Default	Description
`timezone`	string	`"America/Chicago"`	IANA timezone identifier used for notification scheduling and report timing (e.g. `"America/New_York"`, `"Europe/London"`, `"Asia/Tokyo"`).
`marketingEmails`	boolean	`true`	Opt in or out of VoxBurst marketing and product update emails. Does not affect transactional notifications.

Dormant Account Reminders

Dormant account reminders alert you when connected social accounts have gone quiet — either because no post has been published recently or because no posts are scheduled.

Field	Type	Default	Description
`dormantLastPublishedEnabled`	boolean	`false`	Enable reminders for accounts that have not published in a specified number of days.
`dormantLastPublishedDays`	integer	`14`	Number of days since last publish before a reminder is sent. Valid range: 1–365. Only applies when `dormantLastPublishedEnabled` is `true`.
`dormantNoScheduledEnabled`	boolean	`false`	Enable reminders for accounts that have no upcoming scheduled posts.
`dormantNoScheduledDays`	integer	`7`	Number of days with no scheduled posts before a reminder is sent. Valid range: 1–365. Only applies when `dormantNoScheduledEnabled` is `true`.
`dormantWatchedAccountIds`	string[]	`[]`	IDs of connected accounts to watch for dormancy. An empty array watches all accounts in the workspace. A non-empty array restricts reminders to only the listed account IDs.

Partial Updates

PUT /v1/settings/notifications accepts partial updates — only include the fields you want to change. Omitted fields retain their current values. This means you can toggle a single preference without needing to re-send the full preferences object:


# Disable weekly digest only — all other preferences unchanged
curl -X PUT https://api.voxburst.io/v1/settings/notifications \
  -H "Authorization: Bearer eyJexample..." \
  -H "Content-Type: application/json" \
  -d '{ "weeklyDigest": false }'

Error Codes

HTTP	Description
400	Request body failed validation. `dormantLastPublishedDays` or `dormantNoScheduledDays` out of range (must be 1–365), or a field has an incorrect type.
401	Missing or invalid Bearer token.