Notifications

Control which platform events trigger email notifications. By default, all notification types are enabled.

View preferences

curl https://api.fold.run/notifications/preferences \
  -H "Authorization: Bearer YOUR_TOKEN"

Response:

{
  "deploy_success": true,
  "deploy_failure": true,
  "billing_payment_failed": true,
  "billing_subscription_canceled": true,
  "billing_pro_upgrade": true,
  "billing_trial_ended": true,
  "team_invite": true,
  "team_invite_accepted": true,
  "usage_alerts": true,
  "product_updates": true
}

Update preferences

Send only the keys you want to change:

curl -X PUT https://api.fold.run/notifications/preferences \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "deploy_success": false,
    "product_updates": false
  }'

Returns the full preference object with your changes applied.

Available notification types

Key	Default	Description
deploy_success	on	A function deployed successfully
deploy_failure	on	A deployment failed
billing_payment_failed	on	A payment was declined
billing_subscription_canceled	on	Your subscription was canceled
billing_pro_upgrade	on	You upgraded to the Pro plan
billing_trial_ended	on	Your free trial has ended
team_invite	on	You were invited to a team
team_invite_accepted	on	Someone accepted your team invite
usage_alerts	on	A usage alert threshold was exceeded
product_updates	on	Platform news and feature announcements

Workspace-scoped notifications

Override your global preferences on a per-workspace basis. Workspace preferences take priority — if you disable deploy_success for a specific workspace, you won't receive deploy emails for that workspace even if the global setting is enabled.

View workspace preferences

curl https://api.fold.run/workspaces/ws_abc123/notification-preferences \
  -H "Authorization: Bearer YOUR_TOKEN"

Workspace preferences support a subset of event types — the ones most relevant at the workspace level:

Key	Description
deploy_success	A function in this workspace deployed successfully
deploy_failure	A deployment in this workspace failed
usage_alerts	A usage alert threshold was exceeded
team_invite	You were invited to this workspace
team_invite_accepted	Someone accepted a workspace invite

Response:

{
  "preferences": [
    { "event_type": "deploy_success", "enabled": true },
    { "event_type": "deploy_failure", "enabled": true },
    { "event_type": "usage_alerts", "enabled": true },
    { "event_type": "team_invite", "enabled": true },
    { "event_type": "team_invite_accepted", "enabled": true }
  ]
}

All event types default to enabled. Only preferences you've explicitly set are stored — the rest fall back to enabled.

Billing and product update preferences are account-level only — use global preferences for those.

Update workspace preferences

Send only the event types you want to change:

curl -X PUT https://api.fold.run/workspaces/ws_abc123/notification-preferences \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "preferences": [
      { "event_type": "deploy_success", "enabled": false }
    ]
  }'

Returns the full preference list with your changes applied.

Via the SDK

// Get workspace notification preferences
const { preferences } = await fold.getWorkspaceNotificationPreferences('ws_abc123');

// Update workspace notification preferences
await fold.updateWorkspaceNotificationPreferences('ws_abc123', [
  { event_type: 'deploy_success', enabled: false },
]);

Dashboard

Manage workspace notification preferences from the workspace settings page at app.fold.run/console/workspaces. Select a workspace, then navigate to Notification preferences.

Inbox

The inbox is an in-app notification center. Platform events (deploys, alerts, team invites, etc.) appear in the inbox alongside email notifications. Use the inbox for real-time awareness without email noise.

List notifications

curl "https://api.fold.run/inbox?limit=20" \
  -H "Authorization: Bearer YOUR_TOKEN"

Parameter	Type	Default	Description
unread	boolean	false	Only return unread notifications
limit	number	50	Max results (max 100)
before	string	—	ISO timestamp cursor for pagination

Response:

{
  "notifications": [
    {
      "id": "inb_abc123",
      "type": "deploy_success",
      "title": "Function deployed",
      "body": "my-api v3 deployed successfully",
      "link": "/console/deploys",
      "read": false,
      "created_at": "2026-03-24T10:30:00Z"
    }
  ],
  "unread_count": 5,
  "has_more": false
}

Unread count

Lightweight endpoint for badge polling:

curl "https://api.fold.run/inbox/count" \
  -H "Authorization: Bearer YOUR_TOKEN"

Returns { "unread_count": 5 }.

Mark as read

# Mark a single notification as read
curl -X PATCH "https://api.fold.run/inbox/inb_abc123/read" \
  -H "Authorization: Bearer YOUR_TOKEN"

# Mark all notifications as read
curl -X POST "https://api.fold.run/inbox/read-all" \
  -H "Authorization: Bearer YOUR_TOKEN"

Delete a notification

curl -X DELETE "https://api.fold.run/inbox/inb_abc123" \
  -H "Authorization: Bearer YOUR_TOKEN"

Via the SDK

// List inbox notifications
const { notifications, unread_count } = await fold.getInbox({ unread: true });

// Get unread count (lightweight)
const { unread_count } = await fold.getInboxCount();

// Mark as read
await fold.markInboxRead('inb_abc123');
await fold.markAllInboxRead();

// Delete
await fold.deleteInboxItem('inb_abc123');

Inbox API reference

Method	Endpoint	Description
GET	/inbox	List notifications
GET	/inbox/count	Unread count
PATCH	/inbox/:id/read	Mark read
POST	/inbox/read-all	Mark all read
DELETE	/inbox/:id	Delete notification

Tips

• Keep deploy_failure and billing_payment_failed enabled — these are the most important operational alerts.
• Turn off deploy_success if you deploy frequently and the notifications become noisy.
• Use webhooks or usage alerts for programmatic notifications instead of email.