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.ListAsync
List your notifications
Task<NotificationPage> ListAsync( int? limit = null, string? cursor = null, string? apiKey = null, CancellationToken cancellationToken = default)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.AcceptInvitationAsync or Account.DeclineInvitationAsync 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.
The SDK reshapes the wire envelope: the server's data list arrives as items, and unreadCount comes along, so the result is a NotificationPage rather than a plain Page.
Parameters
limitint?Page size, from 1 to 50. The server defaults to 20.
cursorstring?The
nextCursorof the previous page. Leave it out for the first page.apiKeystring?Overrides the client's API key for this call only.
cancellationTokenCancellationTokenCancels the request.
Returns
A NotificationPage with items, unreadCount, hasMore and nextCursor. Each item is an object with object, id, kind, read, readAt, notifiedAt and invitation, which is null or an object with id, workspaceId, workspaceName, roleName, inviterName, inviterEmail, inviterImage, addresses, status and expiresAt. Looping over the page or counting it goes through items.
Example
using Nextmail.Constants; var page = await client.Notifications.ListAsync(limit: 20); Console.WriteLine($"{page.UnreadCount} unread"); foreach (var notification in page){ var invitation = notification["invitation"]; if ((string?)invitation?["status"] == NotificationInvitationStatuses.Open) { Console.WriteLine($"Invited to {invitation["workspaceName"]} as {invitation["roleName"]}"); }} if (page.HasMore){ var older = await client.Notifications.ListAsync(limit: 20, cursor: page.NextCursor); Console.WriteLine($"{older.Count} older notifications");}Notes
An invitation sent again comes back to the top unread, so
notifiedAtis when the person was last told, not when the invitation was first sent.The values of
kindare inNextmail.Constants.NotificationKinds, and those ofinvitation.statusinNextmail.Constants.NotificationInvitationStatuses.addressescounts the addresses and the whole domains the invitation gives together.A cursor that names nothing in this list is 400
invalid_cursor.
Also available in
Notifications.UnreadCountAsync
Count your unread notifications
Task<JsonObject> UnreadCountAsync( string? apiKey = null, CancellationToken cancellationToken = default)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 ListAsync, so poll this one and list only when it changes.
Parameters
apiKeystring?Overrides the client's API key for this call only.
cancellationTokenCancellationTokenCancels the request.
Returns
A JsonObject with object set to notification_count and unreadCount.
Example
var count = await client.Notifications.UnreadCountAsync(); if ((int?)count["unreadCount"] > 0){ Console.WriteLine($"{count["unreadCount"]} new notifications");}Notes
An invitation sent to the person before they signed up counts as soon as they have an account.
Also available in
Notifications.MarkReadAsync
Mark notifications read
Task<JsonObject> MarkReadAsync( IEnumerable<string> ids, string? apiKey = null, CancellationToken cancellationToken = default)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.
Parameters
idsIEnumerable<string>RequiredNotification ids from
ListAsync, 1 to 100 of them.apiKeystring?Overrides the client's API key for this call only.
cancellationTokenCancellationTokenCancels the request.
Returns
A JsonObject with object set to notifications_read, marked and the unreadCount left.
Example
var page = await client.Notifications.ListAsync();var unread = page.Where(notification => (bool?)notification["read"] == false).Select(notification => (string?)notification["id"]).OfType<string>().ToList(); if (unread.Count > 0){ var result = await client.Notifications.MarkReadAsync(unread); Console.WriteLine($"{result["marked"]} marked read, {result["unreadCount"]} still unread");}Notes
Retried automatically on network failure, since marking a notification read twice changes nothing.
Also available in
Notifications.MarkAllReadAsync
Mark every notification read
Task<JsonObject> MarkAllReadAsync( string? apiKey = null, CancellationToken cancellationToken = default)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.
Parameters
apiKeystring?Overrides the client's API key for this call only.
cancellationTokenCancellationTokenCancels the request.
Returns
A JsonObject with object set to notifications_read, marked and the unreadCount left, which is 0 unless a notification arrived meanwhile.
Example
var result = await client.Notifications.MarkAllReadAsync(); Console.WriteLine($"{result["marked"]} marked read");Notes
Retried automatically on network failure, since marking everything read twice changes nothing.
Also available in
Notifications.ClearAsync
Clear your notifications
Task<JsonObject> ClearAsync( bool? declineInvitations = null, string? apiKey = null, CancellationToken cancellationToken = default)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 declineInvitations: is true: then every open invitation is declined first, as Account.DeclineInvitationAsync declines one, and its notification goes too. A declined invitation cannot be accepted, so only a new invitation brings the person in.
Parameters
declineInvitationsbool?Decline every invitation that is still open first, so its notification goes too. False when left out, which keeps open invitations and their notifications.
apiKeystring?Overrides the client's API key for this call only.
cancellationTokenCancellationTokenCancels the request.
Returns
A JsonObject 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
var result = await client.Notifications.ClearAsync(); if ((int?)result["openInvitations"] > 0){ Console.WriteLine($"{result["openInvitations"]} invitations are still open and stay listed");}Notes
Retried automatically on network failure, since clearing again removes nothing more and declines nothing twice.
Google Workspace