# Notifications

> Your bell: what happened that needs a look, and what you choose to hear about. 5 REST endpoints with parameters, permissions and curl examples.

Canonical: https://ballast.to/docs/api/notifications

[API reference](https://ballast.to/docs/api)

Your bell: what happened that needs a look, and what you choose to hear about. 5 endpoints, each also a tool for your AI through [MCP](https://ballast.to/docs/mcp). Authentication and errors are on the [overview](https://ballast.to/docs/api#authentication).

## Your notifications in this workspace, newest first

GET

/api/v1/notifications

Paused campaigns, stopped mailboxes, spam complaints, billing problems, urgent and positive replies, finished placement tests and more, as each person chose in Settings \> Notifications. Kept 90 days.

MCP tool

list\_notifications

Read-only

Parameters

- **`unread` query · boolean**: Only unread ones
- **`cursor` query · string | null**: The \`next\` of the previous page
- **`limit` query · integer**

Returns

- **`notifications` required object\[\]**
- **`unread` required number**
- **`next` required string | null**

cURL

```
curl https://ballast.to/api/v1/notifications \
  -H "Authorization: Bearer $BALLAST_API_KEY"
```

## How many of your notifications are unread

GET

/api/v1/notifications/unread

Read-only

Returns

- **`unread` required number**

cURL

```
curl https://ballast.to/api/v1/notifications/unread \
  -H "Authorization: Bearer $BALLAST_API_KEY"
```

## Mark notifications read (or unread)

POST

/api/v1/notifications/read

Read ones are never emailed in the digest.

MCP tool

mark\_notifications\_read

Parameters

- **`ids` string\[\]**: Left out = all of yours in this workspace
- **`read` boolean**

Returns

- **`updated` required number**
- **`unread` required number**

cURL

```
curl -X POST https://ballast.to/api/v1/notifications/read \
  -H "Authorization: Bearer $BALLAST_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"ids":[],"read":true}'
```

## What you get notified about in this workspace, and the email digest

GET

/api/v1/notifications/settings

Read-only

Returns

- **`digestEvery` required number**: Minutes a notification stays unread before the digest email: 30, 60, 180, 1440, or 0 = never
- **`kinds` required object\[\]**

cURL

```
curl https://ballast.to/api/v1/notifications/settings \
  -H "Authorization: Bearer $BALLAST_API_KEY"
```

## Change what you get notified about

PATCH

/api/v1/notifications/settings

Parameters

- **`digestEvery` 30 | 60 | 180 | 1440 | 0**
- **`kinds` object\[\]**

Returns

- **`digestEvery` required number**: Minutes a notification stays unread before the digest email: 30, 60, 180, 1440, or 0 = never
- **`kinds` required object\[\]**

cURL

```
curl -X PATCH https://ballast.to/api/v1/notifications/settings \
  -H "Authorization: Bearer $BALLAST_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"digestEvery":{},"kinds":[]}'
```