--- title: "nextmail notifications" description: "Every command in this namespace, with its arguments, flags and examples." url: "https://nextmail.sh/docs/cli/reference/notifications" area: "CLI" category: "Reference" --- # nextmail notifications Every command in this namespace, with its arguments, flags and examples. ## Commands ### `nextmail notifications list` List your notifications ```bash nextmail notifications list [flags] ``` Resolves 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`. - Needs a sign-in. - Aliases: `ls`. **Flags** - `--limit ` (default `20`): Page size, from 1 to 50. The server defaults to 20. - `--cursor `: The `nextCursor` of the previous page. Leave it out for the first page. **Examples** ```bash nextmail notifications list ``` Print the raw JSON ```bash nextmail notifications list --json ``` 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); Go [`Notifications.List`](https://nextmail.sh/docs/go/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). ### `nextmail notifications unread-count` Count your unread notifications ```bash nextmail notifications unread-count [flags] ``` Resolves 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`. - Needs a sign-in. **Examples** ```bash nextmail notifications unread-count ``` Print the raw JSON ```bash nextmail notifications unread-count --json ``` 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); Go [`Notifications.UnreadCount`](https://nextmail.sh/docs/go/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). ### `nextmail notifications mark-read` Mark notifications read ```bash nextmail notifications mark-read [flags] ``` 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`. - Needs a sign-in. **Arguments** - `` (required): Notification ids from `list`, 1 to 100 of them. **Examples** ```bash nextmail notifications mark-read notification_4c1b257a ``` Print the raw JSON ```bash nextmail notifications mark-read notification_4c1b257a --json ``` 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); Go [`Notifications.MarkRead`](https://nextmail.sh/docs/go/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). ### `nextmail notifications mark-all-read` Mark every notification read ```bash nextmail notifications mark-all-read [flags] ``` 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`. - Needs a sign-in. **Examples** ```bash nextmail notifications mark-all-read ``` Print the raw JSON ```bash nextmail notifications mark-all-read --json ``` 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); Go [`Notifications.MarkAllRead`](https://nextmail.sh/docs/go/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). ### `nextmail notifications clear` Clear your notifications ```bash nextmail notifications clear [flags] ``` 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 `--decline-invitations` 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`. - Needs a sign-in. **Flags** - `--decline-invitations`: Decline every invitation that is still open first, so its notification goes too. False when left out, which keeps open invitations and their notifications. **Examples** ```bash nextmail notifications clear ``` Print the raw JSON ```bash nextmail notifications clear --json ``` 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); Go [`Notifications.Clear`](https://nextmail.sh/docs/go/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).