---
title: "client.Notifications"
description: "Every method in this namespace: its signature, its parameters, what it returns and an example."
url: "https://nextmail.sh/docs/go/reference/notifications"
area: "Go"
category: "Reference"
---

# client.Notifications

Every method in this namespace: its signature, its parameters, what it returns and an example.

## Methods

What the bell in the app shows the person behind the key or the app: the invitations to join a workspace sent to their address, read or unread, open or answered, with the count of unread ones and a way to mark them read.

### `Notifications.List`

List your notifications

```go
List(ctx context.Context, opts ...nextmail.RequestOption) (*nextmail.NotificationPage, error)
```

Returns one page of the notifications of the person behind the key or the app, newest first, as the bell in the app lists them, with `UnreadCount` for every unread one on any page.

Today each notification is an invitation to join a workspace, sent to the address the person signs in with. It stays listed once it is answered, withdrawn or expires, and `invitation.status` says which: `open`, `accepted`, `declined`, `withdrawn` or `expired`. Answer an open one with `Account.AcceptInvitation` or `Account.DeclineInvitation` and the id in `invitation.id`, which also marks it read. New kinds of notification will be added, and `invitation` is null on a kind that is about something else, so skip a `kind` you do not know.

Scopes: `account:read`.

**Parameters**

- `nextmail.WithLimit` (`int`): Page size, from 1 to 50. The server defaults to 20.
- `nextmail.WithCursor` (`string`): The `NextCursor` of the previous page. Leave it out for the first page.
- `nextmail.WithAPIKey` (`string`): Overrides the client's API key for this call only.

**Returns**

The `*nextmail.NotificationPage` with `Items`, `UnreadCount`, `HasMore` and `NextCursor`. Each notification has `object` set to `notification`, `id`, `kind`, `read`, `readAt`, `notifiedAt` and `invitation`, which is null or has `id`, `workspaceId`, `workspaceName`, `roleName`, `inviterName`, `inviterEmail`, `inviterImage`, `addresses`, `status` and `expiresAt`.

**Example**

```go
page, err := client.Notifications.List(ctx)
if err != nil {
	return err
}

fmt.Println(page.UnreadCount, "unread")

for _, notification := range page.Items {
	invitation := notification.Object("invitation")

	if invitation.String("status") == constants.NotificationInvitationStatusesOpen {
		fmt.Println("Invited to", invitation.String("workspaceName"))
	}
}
```

**Notes**

- Every `kind` is in `constants.NotificationKindsValues`, and every `invitation.status` in `constants.NotificationInvitationStatusesValues`.
- An invitation sent again comes back to the top unread, so `notifiedAt` is when the person was last told, not when the invitation was first sent.
- A cursor that names nothing in this list is 400 `invalid_cursor`.

Also available in: API [`GET /notifications`](https://nextmail.sh/docs/api/reference/your-account#get-notifications); TypeScript [`notifications.list()`](https://nextmail.sh/docs/sdk/reference/notifications#list); Python [`notifications.list()`](https://nextmail.sh/docs/python/reference/notifications#list); Ruby [`notifications.list`](https://nextmail.sh/docs/ruby/reference/notifications#list); PHP [`notifications->list`](https://nextmail.sh/docs/php/reference/notifications#list); Java [`notifications().list`](https://nextmail.sh/docs/java/reference/notifications#list); C# [`Notifications.ListAsync`](https://nextmail.sh/docs/csharp/reference/notifications#list); CLI [`nextmail notifications list`](https://nextmail.sh/docs/cli/reference/notifications#notifications-list).

### `Notifications.UnreadCount`

Count your unread notifications

```go
UnreadCount(ctx context.Context, opts ...nextmail.RequestOption) (nextmail.Object, error)
```

Returns how many notifications the person behind the key or the app has not read yet, the number on the bell in the app. It is cheaper than `List`, so poll this one and list only when it changes.

Scopes: `account:read`.

**Parameters**

- `nextmail.WithAPIKey` (`string`): Overrides the client's API key for this call only.

**Returns**

The `nextmail.Object` with `object` set to `notification_count` and `unreadCount`.

**Example**

```go
count, err := client.Notifications.UnreadCount(ctx)
if err != nil {
	return err
}

if unread := count.Int("unreadCount"); unread > 0 {
	fmt.Println(unread, "new notifications")
}
```

**Notes**

- An invitation sent to the person before they signed up counts as soon as they have an account.

Also available in: API [`GET /notifications/unread-count`](https://nextmail.sh/docs/api/reference/your-account#get-notifications-unread-count); TypeScript [`notifications.unreadCount()`](https://nextmail.sh/docs/sdk/reference/notifications#unreadCount); Python [`notifications.unread_count()`](https://nextmail.sh/docs/python/reference/notifications#unreadCount); Ruby [`notifications.unread_count`](https://nextmail.sh/docs/ruby/reference/notifications#unreadCount); PHP [`notifications->unreadCount`](https://nextmail.sh/docs/php/reference/notifications#unreadCount); Java [`notifications().unreadCount`](https://nextmail.sh/docs/java/reference/notifications#unreadCount); C# [`Notifications.UnreadCountAsync`](https://nextmail.sh/docs/csharp/reference/notifications#unreadCount); CLI [`nextmail notifications unread-count`](https://nextmail.sh/docs/cli/reference/notifications#notifications-unread-count).

### `Notifications.MarkRead`

Mark notifications read

```go
MarkRead(ctx context.Context, ids []string, opts ...nextmail.RequestOption) (nextmail.Object, error)
```

Marks the notifications with these ids read, up to 100 at a time. An id that is already read, or that is not one of the person's notifications, is skipped, so `marked` counts only the ones that changed. Reading a notification never answers it: an open invitation stays open.

Scopes: `account:write`.

**Parameters**

- `ids` (`[]string`, required): Notification ids from `List`, 1 to 100 of them.
- `nextmail.WithAPIKey` (`string`): Overrides the client's API key for this call only.

**Returns**

The `nextmail.Object` with `object` set to `notifications_read`, `marked` and the `unreadCount` left.

**Example**

```go
page, err := client.Notifications.List(ctx)
if err != nil {
	return err
}

unread := []string{}

for _, notification := range page.Items {
	if !notification.Bool("read") {
		unread = append(unread, notification.ID())
	}
}

if len(unread) == 0 {
	return nil
}

result, err := client.Notifications.MarkRead(ctx, unread)
if err != nil {
	return err
}

fmt.Println(result.Int("marked"), "marked read,", result.Int("unreadCount"), "left")
```

**Notes**

- Retried automatically on network failure, since marking a notification read twice changes nothing.

Also available in: API [`POST /notifications/read`](https://nextmail.sh/docs/api/reference/your-account#post-notifications-read); TypeScript [`notifications.markRead()`](https://nextmail.sh/docs/sdk/reference/notifications#markRead); Python [`notifications.mark_read()`](https://nextmail.sh/docs/python/reference/notifications#markRead); Ruby [`notifications.mark_read`](https://nextmail.sh/docs/ruby/reference/notifications#markRead); PHP [`notifications->markRead`](https://nextmail.sh/docs/php/reference/notifications#markRead); Java [`notifications().markRead`](https://nextmail.sh/docs/java/reference/notifications#markRead); C# [`Notifications.MarkReadAsync`](https://nextmail.sh/docs/csharp/reference/notifications#markRead); CLI [`nextmail notifications mark-read`](https://nextmail.sh/docs/cli/reference/notifications#notifications-mark-read).

### `Notifications.MarkAllRead`

Mark every notification read

```go
MarkAllRead(ctx context.Context, opts ...nextmail.RequestOption) (nextmail.Object, error)
```

Marks every notification of the person behind the key or the app read, as Mark all as read in the app does, and clears the number on the bell. Open invitations stay open and can still be answered.

Scopes: `account:write`.

**Parameters**

- `nextmail.WithAPIKey` (`string`): Overrides the client's API key for this call only.

**Returns**

The `nextmail.Object` with `object` set to `notifications_read`, `marked` and the `unreadCount` left, which is 0 unless a notification arrived meanwhile.

**Example**

```go
result, err := client.Notifications.MarkAllRead(ctx)
if err != nil {
	return err
}

fmt.Println(result.Int("marked"), "marked read")
```

**Notes**

- Retried automatically on network failure, since marking everything read twice changes nothing.

Also available in: API [`POST /notifications/read-all`](https://nextmail.sh/docs/api/reference/your-account#post-notifications-read-all); TypeScript [`notifications.markAllRead()`](https://nextmail.sh/docs/sdk/reference/notifications#markAllRead); Python [`notifications.mark_all_read()`](https://nextmail.sh/docs/python/reference/notifications#markAllRead); Ruby [`notifications.mark_all_read`](https://nextmail.sh/docs/ruby/reference/notifications#markAllRead); PHP [`notifications->markAllRead`](https://nextmail.sh/docs/php/reference/notifications#markAllRead); Java [`notifications().markAllRead`](https://nextmail.sh/docs/java/reference/notifications#markAllRead); C# [`Notifications.MarkAllReadAsync`](https://nextmail.sh/docs/csharp/reference/notifications#markAllRead); CLI [`nextmail notifications mark-all-read`](https://nextmail.sh/docs/cli/reference/notifications#notifications-mark-all-read).

### `Notifications.Clear`

Clear your notifications

```go
Clear(ctx context.Context, opts ...nextmail.RequestOption) (nextmail.Object, error)
```

Removes the notifications of the person behind the key or the app, as Clear notifications in the app does. The notification of an invitation that is still open stays, because the invitation still waits for an answer, unless `nextmail.WithDeclineInvitations` is true: then every open invitation is declined first, as `Account.DeclineInvitation` declines one, and its notification goes too. A declined invitation cannot be accepted, so only a new invitation brings the person in.

Scopes: `account:write`.

**Parameters**

- `nextmail.WithDeclineInvitations` (`bool`): Decline every invitation that is still open first, so its notification goes too. False when left out, which keeps open invitations and their notifications.
- `nextmail.WithAPIKey` (`string`): Overrides the client's API key for this call only.

**Returns**

The `nextmail.Object` with `object` set to `notifications_cleared`, how many notifications were `cleared`, how many invitations it declined (`declinedInvitations`), how many are still open (`openInvitations`) and the `unreadCount` left.

**Example**

```go
result, err := client.Notifications.Clear(ctx)
if err != nil {
	return err
}

if open := result.Int("openInvitations"); open > 0 {
	fmt.Println(open, "invitations are still open and stay listed")
}
```

**Notes**

- Retried automatically on network failure, since clearing again removes nothing more and declines nothing twice.

Also available in: API [`POST /notifications/clear`](https://nextmail.sh/docs/api/reference/your-account#post-notifications-clear); TypeScript [`notifications.clear()`](https://nextmail.sh/docs/sdk/reference/notifications#clear); Python [`notifications.clear()`](https://nextmail.sh/docs/python/reference/notifications#clear); Ruby [`notifications.clear`](https://nextmail.sh/docs/ruby/reference/notifications#clear); PHP [`notifications->clear`](https://nextmail.sh/docs/php/reference/notifications#clear); Java [`notifications().clear`](https://nextmail.sh/docs/java/reference/notifications#clear); C# [`Notifications.ClearAsync`](https://nextmail.sh/docs/csharp/reference/notifications#clear); CLI [`nextmail notifications clear`](https://nextmail.sh/docs/cli/reference/notifications#notifications-clear).