Advanced Notification System

TinyKit Pro includes a comprehensive notification system that supports both in-app and email delivery with advanced admin management capabilities.

Notification Features

🔔 Multi-Channel Delivery: In-app notifications with email fallback/supplement
🎯 Smart Targeting: Send to all users, team owners, specific teams, or individual users
📧 Email Integration: Powered by Resend with automatic test mode detection
🧪 Test Mode: Safe testing environment with user-specific test email routing
👑 Admin Broadcasting: System-wide announcements and targeted messaging
📊 Delivery Tracking: Real-time status tracking and delivery confirmation
🔍 Notification History: Comprehensive admin view with user details and search
🎨 Template System: Multiple email templates for different notification types

Notification Types

The system supports various notification types optimized for different use cases:

export type NotificationType =
  | "admin_announcement" // System-wide announcements
  | "system_maintenance" // Maintenance and downtime notifications
  | "team_invitation" // Team invitation and membership
  | "team_member_joined" // New member notifications
  | "billing_update" // Subscription and billing-related
  | "subscription_created" // New subscription confirmations
  | "subscription_updated" // Plan changes and modifications
  | "subscription_canceled" // Cancellation alerts
  | "role_change" // Role change notifications
  | "security_alert" // Security-related notifications
  | "feature_update" // New feature announcements
  | "welcome_message"; // User onboarding messages

Admin Notification Management

Accessing Admin Panel

Navigate to /admin/notifications to access the comprehensive notification management interface.

Sending Notifications

The admin interface provides a powerful form for creating notifications:

Form Fields

Notification Type: Select appropriate type from dropdown
Title: Notification headline (max 100 characters)
Message: Main notification content (max 500 characters)
Link: Optional call-to-action URL
Delivery Channels: Choose in-app, email, or both
Email Template: Select template for email notifications
Target Audience: Choose recipient scope

Targeting Options

All Users: System-wide broadcast to every user (admin only)
All Team Owners: Broadcast to all team owners across the platform
Specific Team: Send to all members of a selected team
Specific Team Owner: Send to the owner of a specific team
Specific User: Send to an individual user

Smart Search System

The admin interface includes efficient search capabilities:

Debounced Search: 300ms delay with minimum 2 characters
Team Search: Find teams by name with member count display
User Search: Find users by name or email with role indicators
Result Limits: Configurable result counts (default: 20)

Notification History

Comprehensive notification tracking with:

User Details: Shows actual recipient names and email addresses
Broadcast Context: Clear indication of broadcast type and scope
Delivery Status: Real-time tracking of email and in-app delivery
Search & Filter: Find notifications by type, status, or content
Detailed View: Complete notification details with metadata

Email Test Mode

Automatic Test Mode Detection

The system intelligently handles test mode:

Development Environment: Automatically detects Resend test mode
Test Email Selection: Choose from validated Resend test addresses
Smart Routing: Routes emails to test addresses during development
Production Safety: Prevents accidental test emails in production

Test Email Options

Select from these validated test addresses:

delivered@resend.dev - Simulates successful delivery
bounced@resend.dev - Simulates email bounce
complained@resend.dev - Simulates spam complaint

Test Mode Benefits

Safe Testing: Never accidentally send emails to real users in development
Behavior Simulation: Test different delivery scenarios
Detailed Logging: Track which user each test email was intended for
Admin Awareness: Clear test mode indicators in the admin interface

Email System Configuration

Required Environment Variables

Configure these in your Convex environment (not .env.local):

# Email system configuration
npx convex env set RESEND_API_KEY re_your_api_key_here
npx convex env set SITE_URL http://localhost:3000
npx convex env set EMAIL_FROM "TinyKit Pro <noreply@yourdomain.com>"

Email Templates

The system includes specialized email templates:

GeneralNotificationEmail: General notifications and system announcements
TeamInvitationEmail: Team invitations with role information
BillingUpdateEmail: Payment and subscription notifications
WelcomeMessageEmail: User onboarding and welcome messages

API Documentation

Admin Functions (Suffix Pattern)

All admin notification functions follow the *Admin suffix pattern:

Queries

// Get paginated notification history with filters
api.notifications.public.queries.getAllNotificationsAdmin({
  paginationOpts: { numItems: 20 },
  type?: "admin_announcement",
  teamId?: "team123",
  isRead?: false
});

// Get system-wide notification statistics
api.notifications.public.queries.getNotificationStatsAdmin();

// Check system health and email delivery status
api.notifications.public.queries.getSystemHealthAdmin();

Mutations

// Send to all system users (admin only)
api.notifications.public.mutations.sendNotificationToAllUsersAdmin({
  type: "admin_announcement",
  title: "System Update",
  message: "Scheduled maintenance tonight at 10 PM EST",
  deliveryChannels: ["in-app", "email"],
  emailTemplate: "AdminAnnouncementEmail",
});

// Send to all team owners
api.notifications.public.mutations.sendNotificationToAllTeamOwnersAdmin({
  type: "feature_update",
  title: "New Feature Available",
  message: "Check out our latest team collaboration features",
  deliveryChannels: ["in-app", "email"],
});

// Send to specific team owner
api.notifications.public.mutations.sendNotificationToTeamOwnerAdmin({
  teamId: "team123",
  type: "billing_update",
  title: "Payment Method Update Required",
  message: "Please update your billing information",
  deliveryChannels: ["in-app", "email"],
  link: "/teams/example/billing",
});

// Bulk mark notifications as read
api.notifications.public.mutations.bulkMarkAsReadAdmin({
  notificationIds: ["notif1", "notif2", "notif3"],
});

Search Functions

// Search teams for targeting
api.teams.public.queries.searchTeamsAdmin({
  searchQuery: "development",
  limit: 20,
});

// Search users for targeting
api.users.public.queries.searchUsersAdmin({
  searchQuery: "john",
  limit: 20,
});

Database Schema

Notification Records

interface NotificationRecord {
  _id: Id<"notifications">;
  _creationTime: number;
  userId: Id<"users">; // Recipient user
  teamId?: Id<"teams">; // Optional team context
  type: NotificationType; // Notification type
  title: string; // Notification title
  message: string; // Notification content
  deliveryChannels: DeliveryChannel[];
  emailSent?: boolean; // Email delivery status
  emailSentAt?: number; // Email delivery timestamp
  emailTemplate?: string; // Template used for email
  isRead: boolean; // User read status
  readAt?: number; // Read timestamp
  createdAt: number;
  metadata?: {
    targetGroup?: "all_users" | "all_team_owners" | "team_owner";
    testEmail?: string; // Test mode email address
    adminSent?: boolean; // Admin-generated flag
    link?: string; // Action URL
  };
}

Broadcast Context

The system preserves broadcast context while creating individual notification records:

Individual Tracking: Each user gets their own notification record
Broadcast Metadata: Original targeting information preserved
Delivery Status: Separate tracking for in-app and email delivery
Test Mode Support: Test email routing information stored in metadata

Permission System

Role Requirements

Admin: Can send to all users, access all admin functions
Team Admin/Owner: Can send team-specific notifications
Regular Users: Can only manage their own notifications

Permission Checking

// Backend permission validation
export const sendNotificationToAllUsersAdmin = mutation({
  handler: async (ctx, args) => {
    // Require admin role for system-wide broadcasts
    await requireRole(ctx, ["admin"]);

    // Implementation...
  },
});

// Frontend permission checking
const { isAdmin, hasPermission } = usePermissions();

{isAdmin() && <AdminNotificationPanel />}
{hasPermission("notifications:admin") && <SendNotificationButton />}

Development & Testing

Testing Notifications

Create Test Users: Use admin panel to create test users and teams
Send Test Notifications: Use admin interface with test mode enabled
Verify Delivery: Check both in-app and email delivery
Test Targeting: Verify correct users receive targeted notifications
Check History: Confirm notifications appear in admin history

Debug Commands

# View notification-related logs
npx convex logs --tail | grep "notification\|email"

# Check Resend email delivery
# Visit resend.com/emails to see sent emails

# Monitor notification system health
npx convex dashboard
# Navigate to notifications table

Best Practices

Content Guidelines

Concise Titles: Keep titles under 100 characters
Clear Messages: Use action-oriented, helpful language
Appropriate Urgency: Match notification type to content urgency
Consistent Branding: Maintain brand voice across all communications

Technical Best Practices

Permission First: Always check permissions before sending
Batch Operations: Use bulk functions for efficiency
Error Handling: Implement graceful error recovery
Test Mode: Always test in development before production
Monitor Delivery: Track email delivery rates and success

Security Considerations

Access Control: Strict role-based access to admin functions
Audit Trail: Complete tracking of who sent what to whom
Safe Testing: Test mode prevents accidental production emails
Data Protection: Sensitive information excluded from notifications

← Previous: Billing | Next: Site Banners →

Advanced Notification System

On this page