Skip to content
PostyAPIv0.3.81
Menu

API reference

Notification preferences

Get my notification preferences

get/v1/me/notification-preferences

Get the signed-in user's notification profile (email switch, digest times, quiet hours, pause) and per-category delivery with defaults, account-wide overrides and per-workspace overrides. OAuth users only; API keys get 403 user_session_required.

Response 200

Preferences

  • profileNotificationProfilerequired
  • categoriesarray of objectrequired
    Child attributes
    • categorystringrequired

      One ofassigned_workapprovals_and_feedbackpublishing_and_channelsplanning_remindersprogress_updatesinsights_and_celebrations

    • defaultsobjectrequired
      Child attributes
      • inAppEnabledbooleanrequired
      • emailFrequencystringrequired

        One ofoffimmediatedaily_digestweekly_digest

    • overrideobjectrequirednullable
      Child attributes
      • inAppEnabledbooleanrequired
      • emailFrequencystringrequired

        One ofoffimmediatedaily_digestweekly_digest

      • categorystringrequired

        One ofassigned_workapprovals_and_feedbackpublishing_and_channelsplanning_remindersprogress_updatesinsights_and_celebrations

      • workspaceIdstringrequirednullable
      • revisionintegerrequired
  • workspaceOverridesarray of NotificationPreferencerequired

Errors

401
Unauthenticated
403
API key callers: notification preferences belong to a signed-in user
Request
curl "https://api.posty.social/v1/me/notification-preferences" \
  -H "Authorization: Bearer $POSTY_API_KEY"
Response 200
{
  "profile": {
    "emailEnabled": true,
    "timezone": "string",
    "dailyDigestLocalTime": "string",
    "weeklyDigestDay": 1,
    "quietHoursStart": "string",
    "quietHoursEnd": "string",
    "quietHoursBehavior": "defer",
    "pausedUntil": "2026-01-15T09:30:00.000Z",
    "revision": 1
  },
  "categories": [
    {
      "category": "assigned_work",
      "defaults": {
        "inAppEnabled": true,
        "emailFrequency": "off"
      },
      "override": {
        "inAppEnabled": true,
        "emailFrequency": "off",
        "category": "assigned_work",
        "workspaceId": "string",
        "revision": 1
      }
    }
  ],
  "workspaceOverrides": [
    {
      "inAppEnabled": true,
      "emailFrequency": "off",
      "category": "assigned_work",
      "workspaceId": "string",
      "revision": 1
    }
  ]
}

Update my notification preference

put/v1/me/notification-preferences/{category}

Set how the signed-in user hears about one category: in app on or off and the email frequency. scope account applies everywhere; scope workspace overrides it for the current workspace only. Send the override's revision as expectedRevision, or null when none exists. OAuth users only.

Path parameters

  • categorystringrequired

    One ofassigned_workapprovals_and_feedbackpublishing_and_channelsplanning_remindersprogress_updatesinsights_and_celebrations

Request body

  • inAppEnabledbooleanrequired
  • emailFrequencystringrequired

    One ofoffimmediatedaily_digestweekly_digest

  • scopestringrequired

    One ofaccountworkspace

  • expectedRevisionintegerrequirednullable

    Min 0

Response 200

Preference saved

  • inAppEnabledbooleanrequired
  • emailFrequencystringrequired

    One ofoffimmediatedaily_digestweekly_digest

  • categorystringrequired

    One ofassigned_workapprovals_and_feedbackpublishing_and_channelsplanning_remindersprogress_updatesinsights_and_celebrations

  • workspaceIdstringrequirednullable
  • revisionintegerrequired

Errors

400
Invalid request
401
Unauthenticated
403
API key callers: notification preferences belong to a signed-in user
409
Preferences changed since they were read
Request
curl -X PUT "https://api.posty.social/v1/me/notification-preferences/$CATEGORY" \
  -H "Authorization: Bearer $POSTY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "inAppEnabled": true,
  "emailFrequency": "off",
  "scope": "account",
  "expectedRevision": 1
}'
Response 200
{
  "inAppEnabled": true,
  "emailFrequency": "off",
  "category": "assigned_work",
  "workspaceId": "string",
  "revision": 1
}

Update my notification profile

put/v1/me/notification-profile

Replace the signed-in user's notification profile: email master switch, IANA timezone, daily digest time (HH:mm), weekly digest day (0 is Sunday), quiet hours and their behaviour, and an optional pause. Send the profile revision from get_my_notification_preferences as expectedRevision. OAuth users only.

Request body

  • emailEnabledbooleanrequired
  • timezonestringrequired

    Min length 1 · Max length 100

  • dailyDigestLocalTimestringrequired

    Pattern ^(?:[01]\d|2[0-3]):[0-5]\d$

  • weeklyDigestDayintegerrequired

    Min 0 · Max 6

  • quietHoursStartstringrequirednullable

    Pattern ^(?:[01]\d|2[0-3]):[0-5]\d$

  • quietHoursEndstringrequirednullable

    Pattern ^(?:[01]\d|2[0-3]):[0-5]\d$

  • quietHoursBehaviorstringrequired

    One ofdefernext_digest

  • pausedUntilstring (date-time)requirednullable
  • expectedRevisionintegerrequired

    Min 0

Response 200

Profile saved

  • emailEnabledbooleanrequired
  • timezonestringrequired
  • dailyDigestLocalTimestringrequired
  • weeklyDigestDayintegerrequired
  • quietHoursStartstringrequirednullable
  • quietHoursEndstringrequirednullable
  • quietHoursBehaviorstringrequired

    One ofdefernext_digest

  • pausedUntilstring (date-time)requirednullable
  • revisionintegerrequired

Errors

400
Invalid request
401
Unauthenticated
403
API key callers: notification preferences belong to a signed-in user
409
Preferences changed since they were read
Request
curl -X PUT "https://api.posty.social/v1/me/notification-profile" \
  -H "Authorization: Bearer $POSTY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "emailEnabled": true,
  "timezone": "string",
  "dailyDigestLocalTime": "string",
  "weeklyDigestDay": 1,
  "quietHoursStart": "string",
  "quietHoursEnd": "string",
  "quietHoursBehavior": "defer",
  "pausedUntil": "2026-01-15T09:30:00.000Z",
  "expectedRevision": 1
}'
Response 200
{
  "emailEnabled": true,
  "timezone": "string",
  "dailyDigestLocalTime": "string",
  "weeklyDigestDay": 1,
  "quietHoursStart": "string",
  "quietHoursEnd": "string",
  "quietHoursBehavior": "defer",
  "pausedUntil": "2026-01-15T09:30:00.000Z",
  "revision": 1
}

Set workspace notification mute

put/v1/me/workspace-notification-mute

Mute or unmute email from the current workspace for the signed-in user. Muting turns email off for every category in this workspace; unmuting removes this workspace's overrides. OAuth users only.

Request body

  • mutedbooleanrequired

Response 200

Mute saved

  • mutedbooleanrequired
  • changedintegerrequired

Errors

400
Invalid request
401
Unauthenticated
403
API key callers: notification preferences belong to a signed-in user
409
Preferences changed since they were read
Request
curl -X PUT "https://api.posty.social/v1/me/workspace-notification-mute" \
  -H "Authorization: Bearer $POSTY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "muted": true
}'
Response 200
{
  "muted": true,
  "changed": 1
}

Models

Objects referenced by the endpoints above.

NotificationPreference

  • inAppEnabledbooleanrequired
  • emailFrequencystringrequired

    One ofoffimmediatedaily_digestweekly_digest

  • categorystringrequired

    One ofassigned_workapprovals_and_feedbackpublishing_and_channelsplanning_remindersprogress_updatesinsights_and_celebrations

  • workspaceIdstringrequirednullable
  • revisionintegerrequired

NotificationProfile

  • emailEnabledbooleanrequired
  • timezonestringrequired
  • dailyDigestLocalTimestringrequired
  • weeklyDigestDayintegerrequired
  • quietHoursStartstringrequirednullable
  • quietHoursEndstringrequirednullable
  • quietHoursBehaviorstringrequired

    One ofdefernext_digest

  • pausedUntilstring (date-time)requirednullable
  • revisionintegerrequired