Alerts and Reminders
The SetGet Alerts and Reminders system delivers real-time notifications to your team whenever important events occur in your workspace. Whether a work item changes state, a deadline passes, or a teammate mentions you in a comment, the alert system ensures the right people are notified through the right channel at the right time.
Alerts operate at the workspace level and are accessible from the Reminders section in your workspace settings. The system supports three notification channels --- in-app, email, and SMS --- and provides granular control over which events trigger notifications, who receives them, and how they are delivered.
Why alerts matter
In a project management environment with many moving parts, critical updates can easily be missed. A priority escalation, a blocked work item, or an overdue deadline might go unnoticed if team members are not actively watching the project board. The alert system solves this by proactively pushing notifications to the people who need to act.
Key benefits include:
- Reduced response time --- Team members learn about critical changes immediately instead of discovering them during the next standup.
- Accountability --- Assignees and stakeholders receive direct notifications when work items they own or follow are updated.
- Deadline enforcement --- Due date reminders and overdue alerts ensure nothing slips through the cracks.
- Audit trail --- Every notification sent is logged with delivery status, making it easy to verify that alerts reached their intended recipients.
System architecture
The alert system is composed of six interconnected subsystems:
| Subsystem | Purpose | Configuration page |
|---|---|---|
| Triggers | Define which events generate notifications and who receives them | Triggers |
| Templates | 21 system email templates organized by category for consistent formatting | Templates |
| State mappings | Specialized alerts for state-to-state transitions in your workflow | State mappings |
| SMS configuration | Provider setup for SMS delivery via Twilio or HTTP webhook | SMS |
| Preferences | Per-user channel selection for each event type | Preferences |
| History | Send log with delivery status tracking and troubleshooting | History |
The backend supports 24 API endpoints, 6 dedicated services, and 6 MongoDB collections to power the full alert lifecycle from trigger evaluation to delivery confirmation.
Configuration workflow
Setting up alerts in SetGet follows a logical progression. You do not need to complete every step immediately --- the system works with partial configuration and you can expand coverage over time.
Step 1: SMS setup (optional)
If your team needs SMS notifications for urgent events, configure your SMS provider first. This step is optional; email and in-app alerts work without any SMS configuration.
- Navigate to Workspace Settings > Reminders > SMS.
- Choose a provider: Twilio or Generic HTTP webhook.
- Enter the required credentials (see SMS configuration for details).
- Send a test SMS to verify delivery.
TIP
Skip this step if your team only needs in-app and email notifications. You can always add SMS later.
Step 2: User preferences
Each workspace member can configure which notification channels they want to receive for each event type.
- Navigate to Workspace Settings > Reminders > Preferences.
- Review the event-channel matrix.
- Enable or disable channels (in-app, email, SMS) for each of the 16 event types.
- If SMS is enabled for any event, ensure a phone number is registered on the user profile.
See Notification preferences for the full configuration reference.
Step 3: Email triggers
Triggers are the core of the alert system. Each trigger binds an event type to a template and a set of recipients.
- Navigate to Workspace Settings > Reminders > Triggers.
- Click Create Trigger.
- Select the event type (e.g.,
state_changed,due_date_passed). - Choose an email template.
- Define recipients (assignees, creator, subscribers, or specific users).
- Optionally add conditions to narrow the scope.
- Activate the trigger.
See Triggers for the full 16-event reference and step-by-step examples.
Step 4: State mappings
For workflows where specific state transitions require targeted notifications, create state mappings.
- Navigate to Workspace Settings > Reminders > State Mappings.
- Click Create Mapping.
- Select the source state (or leave blank for "any state").
- Select the destination state.
- Choose a template and recipients.
- Activate the mapping.
See State mappings for use cases and configuration details.
Step 5: Template preview and test
Before activating triggers in production, preview and test your templates to ensure they render correctly.
- Navigate to Workspace Settings > Reminders > Templates.
- Select any template to preview it with sample data.
- Click Send Test to deliver a test email or SMS to yourself.
- Verify formatting, variable substitution, and delivery.
See Templates for the full template catalog and variable reference.
Stats dashboard
The Reminders overview page displays a real-time dashboard summarizing your workspace's alert activity:
| Metric | Description |
|---|---|
| Emails sent today | Total email notifications dispatched in the current calendar day |
| SMS sent today | Total SMS messages dispatched in the current calendar day |
| Active triggers | Number of triggers currently enabled and processing events |
| Success rate | Percentage of notifications that were delivered successfully (not failed) |
| Recent sends | A live feed of the most recent notification dispatches with status |
The dashboard provides a quick health check for your notification system. A declining success rate or a spike in failed sends indicates a configuration or delivery issue that should be investigated in the History page.
WARNING
The stats dashboard reflects workspace-wide totals. Individual user send counts are available in the History page with filtering.
Notification channels
SetGet supports three notification channels. Each channel has different characteristics and is suited to different urgency levels.
In-app notifications
In-app notifications appear in the SetGet notification panel accessible from the bell icon in the top navigation bar. They are the lowest-friction channel and are ideal for informational updates that do not require immediate action.
Characteristics:
- Delivered instantly when the event occurs
- Visible only when the user is active in SetGet
- Supports mark-as-read and bulk dismiss
- No external dependencies or configuration required
- Free and unlimited
Best for: General updates, comment notifications, label changes, property updates.
Email notifications
Email notifications are sent to the user's registered email address using the workspace SMTP configuration. They provide a persistent record outside of SetGet and can reach users who are not actively logged in.
Characteristics:
- Delivered via the workspace SMTP server
- Formatted using the 21 system templates
- Supports HTML rendering with work item context
- Delivery tracked in the History log
- Requires SMTP configuration at the instance level
Best for: State changes, assignment updates, due date reminders, mentions, cycle and module updates.
SMS notifications
SMS notifications deliver short text messages to the user's registered phone number. They are the most intrusive channel and should be reserved for truly urgent events.
Characteristics:
- Delivered via Twilio or a custom HTTP webhook
- Limited to plain text with a concise message body
- Incurs per-message cost (Twilio) or depends on your webhook provider's pricing
- Requires SMS provider configuration and a registered phone number per user
- Delivery tracked in the History log
Best for: Overdue deadlines, blocker state transitions, critical priority escalations.
TIP
Use SMS sparingly. Reserve it for events that genuinely require immediate attention. Overusing SMS leads to notification fatigue and users disabling the channel entirely.
How alerts integrate with SetGet
The alert system is deeply integrated with SetGet's core entities. Understanding these integration points helps you design an effective trigger strategy.
Work items
Work items are the primary source of alert events. Virtually every change to a work item --- state, assignee, priority, labels, due date, links, relations, archive status --- can trigger a notification. The alert system receives these events from the NotificationDispatcher in the backend, which auto-subscribes the actor, subscribes assignees, and notifies all other subscribers.
Cycles
When a work item is added to or removed from a cycle, the cycle_changed event fires. This is useful for notifying cycle leads that new work has been scoped into their iteration or that items have been descoped.
Modules
Similarly, the module_changed event fires when work items are associated with or removed from modules. Module owners can use this trigger to stay informed about scope changes.
Comments and mentions
The comment_added and mentioned events integrate with the collaboration layer. When a user is @mentioned in a comment, they receive a targeted notification regardless of whether they are subscribed to the work item.
Due dates
The due_date_passed event is evaluated by a background scheduler that checks for overdue work items. Unlike other events that fire on user actions, due date alerts fire on a time-based schedule.
Alerts vs. automations
SetGet provides two systems that respond to events: Alerts and Automations. While they share some trigger events, they serve fundamentally different purposes.
| Aspect | Alerts | Automations |
|---|---|---|
| Purpose | Notify people about events | Take actions in response to events |
| Output | Notifications (in-app, email, SMS) | State changes, assignments, property updates |
| Configuration | Workspace-level Reminders settings | Project-level Automation settings |
| Scope | Workspace-wide | Per-project |
| User control | Per-user channel preferences | Rule-level enable/disable |
| Typical use | "Tell the team lead when a blocker is created" | "Auto-assign new bugs to the triage queue" |
Use alerts when you want to inform someone. Use automations when you want to change something. In many workflows, you will use both: an automation moves a work item to a new state, and an alert notifies the relevant stakeholders about that state change.
See Automations for details on configuring trigger-action rules.
Access and permissions
Alert configuration requires workspace-level permissions:
| Action | Required role |
|---|---|
| View alert configuration | Workspace Member |
| Create/edit/delete triggers | Workspace Admin |
| Create/edit/delete state mappings | Workspace Admin |
| Configure SMS provider | Workspace Admin |
| Preview and test templates | Workspace Admin |
| Edit personal notification preferences | Any authenticated user |
| View send history | Workspace Admin |
WARNING
Only workspace administrators can create and manage triggers, state mappings, and SMS configuration. Regular members can only adjust their own notification preferences.
Quick start checklist
Use this checklist to get your alert system operational:
- [ ] Verify SMTP is configured at the instance level (required for email alerts)
- [ ] Optionally configure an SMS provider under Reminders > SMS
- [ ] Create at least one trigger for a high-priority event (e.g.,
state_changedordue_date_passed) - [ ] Ask team members to review their notification preferences under Reminders > Preferences
- [ ] Send a test notification from the Templates page to verify delivery
- [ ] Monitor the History page after activation to confirm successful delivery
Data model
The alert system uses six dedicated MongoDB collections to store configuration and history:
| Collection | Purpose | Key fields |
|---|---|---|
alert_triggers | Stores trigger definitions | event_type, template_id, recipients, conditions, enabled |
alert_templates | Stores system email template metadata | name, category, subject, body, sms_body, variables |
alert_state_mappings | Stores state transition mapping rules | from_state, to_state, template_id, recipients, enabled |
alert_sms_config | Stores SMS provider configuration per workspace | provider, credentials (encrypted), workspace_id |
alert_preferences | Stores per-user notification channel preferences | user_id, workspace_id, event_channel_map |
alert_history | Stores send log records with delivery status | channel, recipient, template, trigger, entity, status, error, timestamp |
All collections are indexed on workspace_id for efficient per-workspace queries. The history collection has additional indexes on timestamp, status, and channel for filtering and dashboard aggregation.
API endpoints
The alert system exposes 24 REST API endpoints organized by subsystem:
| Subsystem | Endpoints | Methods |
|---|---|---|
| Triggers | 4 | GET (list), POST (create), PUT (update), DELETE |
| Templates | 3 | GET (list), GET (preview), POST (test send) |
| State mappings | 4 | GET (list), POST (create), PUT (update), DELETE |
| SMS configuration | 3 | GET (current config), PUT (update), POST (test send) |
| Preferences | 3 | GET (current user), PUT (update), POST (reset to defaults) |
| History | 4 | GET (list with filters), GET (detail), GET (stats), GET (export) |
| Dashboard | 3 | GET (today stats), GET (success rate), GET (recent sends) |
All endpoints require workspace-level authentication and appropriate role permissions.
Troubleshooting
| Symptom | Likely cause | Resolution |
|---|---|---|
| No emails being sent | SMTP not configured or credentials invalid | Check instance SMTP settings |
| Emails sent but not received | Spam filter or incorrect recipient address | Check spam folders; verify user email addresses |
| SMS not delivered | SMS provider not configured or invalid credentials | See SMS troubleshooting |
| Trigger not firing | Trigger is disabled or conditions are too restrictive | Check trigger status and conditions in the Triggers page |
| Success rate declining | Delivery failures accumulating | Review failed sends in History |
| Dashboard stats not updating | Background aggregation delay | Stats refresh every 60 seconds; wait and reload |
| Test send works but real triggers do not | Trigger conditions too restrictive | Review conditions; test sends bypass conditions |
Related pages
- Triggers --- Configure event-based notification triggers
- Templates --- Browse and preview system email templates
- State mappings --- Create state transition alerts
- SMS configuration --- Set up SMS delivery providers
- Notification preferences --- Per-user channel configuration
- Alert history --- View send logs and delivery status
- Best practices --- Design an effective notification strategy
- Automations --- Trigger-action rules for automated workflows
- Notifications overview --- General notification system