Skip to main content

Notifications

The client.notifications API manages notification retrieval, dismissal, and policies.

Fetching notifications​

List​

final page = await client.notifications.fetch(limit: 20);

for (final n in page.items) {
  print('${n.type}: ${n.account?.displayName}');
}

Filtering by type​

// Only mentions and favourites
final page = await client.notifications.fetch(
  types: ['mention', 'favourite'],
);

// Everything except follows
final page = await client.notifications.fetch(
  excludeTypes: ['follow'],
);

Single notification​

final notification = await client.notifications.fetchById('12345');

Notification-specific details​

Some v1 notifications include additional details:

final event = notification.relationshipSeveranceEvent; // severed_relationships
final report = notification.report;                    // admin.report
final wasFiltered = notification.filtered;             // Mastodon 4.3+

filtered defaults to false because the server includes it only when true. Grouped v2 notifications expose severance details as group.event and reports as group.report; they do not have a per-notification filtered field.

Unread count (Mastodon 4.3+)​

final count = await client.notifications.fetchUnreadCount();
print(count.count);

Dismissing notifications​

Dismiss one​

await client.notifications.dismiss('12345');

Clear all​

await client.notifications.clear();

Notification policy (Mastodon 4.3+)​

Fetch current policy​

final policy = await client.notifications.fetchPolicy();
print(policy.forNotFollowing); // accept, filter, drop

Update policy​

await client.notifications.updatePolicy(policy);

Notification requests (Mastodon 4.3+)​

Filtered notifications from accounts that match the policy are collected as requests.

List requests​

final page = await client.notifications.fetchRequests(limit: 20);

Accept / dismiss​

// Single
await client.notifications.acceptRequest('12345');
await client.notifications.dismissRequest('12345');

// Batch
await client.notifications.acceptRequests(['1', '2', '3']);
await client.notifications.dismissRequests(['4', '5']);

Check merge status​

final merged = await client.notifications.checkRequestsMerged();
if (merged) {
  // Accepted requests have been merged into the notification list
}

Grouped notifications (v2)​

For the grouped notifications API, use client.groupedNotifications:

final result = await client.groupedNotifications.fetch(limit: 20);
for (final group in result.notificationGroups) {
  print('${group.type}: ${group.notificationsCount} notifications');
}