Managing Notifications

Last updated: January 2026

This guide explains how to manage notifications in the Agglestone Messaging Service, including marking them as read or unread, and deleting them.

Overview

Notifications in a user’s inbox can be managed in several ways:

Mark as Read: Mark notifications as read to track which ones have been viewed
Mark as Unread: Mark notifications as unread if the user wants to revisit them later
Delete: Permanently remove notifications from the inbox

All notification management operations are scoped to the authenticated user – users can only manage their own notifications.

Marking Notifications as Read

Marking a notification as read helps users track which notifications they’ve already viewed. This is useful for displaying unread counts, highlighting new notifications, and managing notification state.

Marking a Notification as Read

Endpoint: PUT /tenant/{tenantId}/v1/Notifications/{notificationId}/read?read=true

Query Parameters:

read (optional, default: true): Set to true to mark as read, false to mark as unread

Response:

200 OK

Example: Marking a Notification as Read

async function markNotificationAsRead(notificationId: string) {
  const response = await fetch(
    `${apiBaseUrl}/tenant/${tenantId}/v1/Notifications/${notificationId}/read?read=true`,
    {
      method: 'PUT',
      headers: {
        'Authorization': `Bearer ${accessToken}`
      }
    }
  );

  if (!response.ok) {
    throw new Error(`Failed to mark notification as read: ${response.statusText}`);
  }

  return response.ok;
}

// Mark a notification as read when user views it
await markNotificationAsRead('notification-id-456');

Marking Multiple Notifications as Read

To mark multiple notifications as read, call the endpoint for each notification:

async function markMultipleNotificationsAsRead(notificationIds: string[]) {
  const results = await Promise.all(
    notificationIds.map(id => markNotificationAsRead(id))
  );
  return results.every(result => result);
}

// Mark multiple notifications as read
await markMultipleNotificationsAsRead([
  'notification-id-1',
  'notification-id-2',
  'notification-id-3'
]);

Marking Notifications as Unread

You can mark notifications as unread if users want to revisit them later or if they want to keep them highlighted in their inbox.

Marking a Notification as Unread

Endpoint: PUT /tenant/{tenantId}/v1/Notifications/{notificationId}/read?read=false

Response:

200 OK

Example: Marking a Notification as Unread

async function markNotificationAsUnread(notificationId: string) {
  const response = await fetch(
    `${apiBaseUrl}/tenant/${tenantId}/v1/Notifications/${notificationId}/read?read=false`,
    {
      method: 'PUT',
      headers: {
        'Authorization': `Bearer ${accessToken}`
      }
    }
  );

  if (!response.ok) {
    throw new Error(`Failed to mark notification as unread: ${response.statusText}`);
  }

  return response.ok;
}

// Mark a notification as unread
await markNotificationAsUnread('notification-id-456');

Deleting Notifications

Users can permanently delete notifications from their inbox. Deleted notifications cannot be recovered.

Deleting a Notification

Endpoint: DELETE /tenant/{tenantId}/v1/Notifications/{notificationId}

Response:

200 OK

Example: Deleting a Notification

async function deleteNotification(notificationId: string) {
  const response = await fetch(
    `${apiBaseUrl}/tenant/${tenantId}/v1/Notifications/${notificationId}`,
    {
      method: 'DELETE',
      headers: {
        'Authorization': `Bearer ${accessToken}`
      }
    }
  );

  if (!response.ok) {
    throw new Error(`Failed to delete notification: ${response.statusText}`);
  }

  return response.ok;
}

// Delete a notification
await deleteNotification('notification-id-456');

Deleting Multiple Notifications

To delete multiple notifications, call the endpoint for each notification:

async function deleteMultipleNotifications(notificationIds: string[]) {
  const results = await Promise.all(
    notificationIds.map(id => deleteNotification(id))
  );
  return results.every(result => result);
}

// Delete multiple notifications
await deleteMultipleNotifications([
  'notification-id-1',
  'notification-id-2',
  'notification-id-3'
]);

Use Cases

Marking All as Read

When a user clicks “Mark all as read”, mark all visible notifications:

async function markAllAsRead(notificationIds: string[]) {
  await markMultipleNotificationsAsRead(notificationIds);
  // Update UI to reflect read state
  updateNotificationUI(notificationIds, 'read');
}

Auto-Mark as Read on View

Automatically mark notifications as read when the user views them:

async function viewNotification(notificationId: string) {
  // Fetch and display the notification
  const notification = await getNotification(notificationId);
  displayNotificationDetails(notification);
  
  // Mark as read if not already read
  if (!notification.readAt) {
    await markNotificationAsRead(notificationId);
  }
}

Cleanup Old Notifications

Allow users to delete old notifications to keep their inbox clean:

async function cleanupOldNotifications(olderThanDays: number) {
  const cutoffDate = new Date();
  cutoffDate.setDate(cutoffDate.getDate() - olderThanDays);
  
  // Load all notifications
  let page = 1;
  let hasMore = true;
  const notificationsToDelete: string[] = [];
  
  while (hasMore) {
    const result = await getNotifications(page, 50);
    
    result.data.forEach(notification => {
      const notificationDate = new Date(notification.createdAt);
      if (notificationDate < cutoffDate) {
        notificationsToDelete.push(notification.id);
      }
    });
    
    hasMore = result.hasNextPage;
    page++;
  }
  
  // Delete old notifications
  if (notificationsToDelete.length > 0) {
    await deleteMultipleNotifications(notificationsToDelete);
  }
}

Unread Count Display

Track and display unread notification counts:

async function getUnreadCount(): Promise<number> {
  const result = await getNotifications(1, 50);
  
  // Count unread notifications (those without readAt)
  const unreadCount = result.data.filter(n => !n.readAt).length;
  
  // If there are more pages, you may need to load them all to get accurate count
  // Or implement a separate unread count endpoint if available
  
  return unreadCount;
}

// Display unread count badge
const unreadCount = await getUnreadCount();
updateUnreadBadge(unreadCount);

Error Handling

Common errors you may encounter:

401 Unauthorized: Your access token is missing, invalid, or expired. Refresh your token and retry.
403 Forbidden: The tenant ID doesn’t match your authentication, or you’re trying to manage another user’s notifications.
404 Not Found: The notification doesn’t exist, or you don’t have access to it.

Always check the response status and handle errors appropriately in your application.

—

Ready to get started? Check out the Quick Start Guide – Notifications.