skills/knock-notification-best-practices/rules/notification-system-implementation.md

---
title: Notification system implementation rules
description: Comprehensive rules for implementing production-ready notification systems including timing, preferences, error handling, and compliance
tags:
  - notifications
  - system-design
  - implementation
  - architecture
  - preferences
  - error-handling
  - monitoring
  - compliance
  - gdpr
  - can-spam
  - testing
  - best-practices
category: knock-notification-best-practices
last_updated: 2026-01-23
---

# Notification system implementation rules

## Core implementation principles

### 1. User-centric design
**Rule**: Always prioritize user value over technical implementation details.

**Application**:
- Lead with benefits, not features
- Respect user preferences and quiet hours
- Implement batching to prevent notification fatigue
- Provide granular control over notification types

### 2. Context is king
**Rule**: Every notification must provide enough context for users to take immediate action.

**Application**:
- Include relevant identifiers (order numbers, user names, amounts)
- Show what changed (from "pending" to "failed")
- Provide action history when relevant
- Link directly to the related object/page

### 3. Multi-channel consistency
**Rule**: Maintain consistent messaging across all channels while respecting channel-specific constraints.

**Application**:
- Use the same terminology across email, push, SMS, and in-app
- Adapt length and format to channel requirements
- Ensure brand voice remains consistent
- Test notifications across all channels before launch

### 4. Progressive disclosure
**Rule**: Start with the minimum information needed, provide paths to learn more.

**Application**:
- Use notification feeds for detailed history
- Use toasts for immediate confirmations
- Use email for comprehensive information
- Use push for urgent, actionable items

## Channel selection rules

### When to use email
**Use email when**:
- Information requires persistent reference
- Content includes detailed instructions or data
- Users need to forward or share information
- Message isn't time-critical
- Rich formatting enhances understanding

**Don't use email when**:
- Action must be immediate
- Information becomes stale quickly
- User is actively in the product
- Message is purely transactional (consider SMS)

### When to use push notifications
**Use push when**:
- Time-sensitivity is critical
- User needs to return to the app
- Action required impacts ongoing work
- External events affect user's data

**Don't use push when**:
- Information is low-priority
- User is already active in app
- Message requires extended reading
- Notification is part of a high-frequency stream

### When to use SMS
**Use SMS when**:
- Delivery must be guaranteed
- User may not have app access
- Authentication or security is involved
- Time-criticality is extreme

**Don't use SMS when**:
- Message contains sensitive data
- Rich formatting is needed
- Cost of delivery outweighs value
- Email or push would suffice

### When to use in-app
**Use in-app when**:
- User is actively using the product
- Action can wait until next session
- Building notification history is valuable
- Guiding user through a flow

**Don't use in-app when**:
- User needs notification while away
- Information expires before next session
- Immediate attention required
- User isn't likely to check feed regularly

### When to use chat (Slack/Teams)
**Use chat when**:
- Team collaboration is core to the action
- Immediate team visibility is valuable
- Discussion may follow the notification
- Integration with team workflows matters

**Don't use chat when**:
- Information is personal/private
- Team coordination isn't required
- User isn't active on the platform
- Notification would create channel noise

## Timing and frequency rules

### Timing rules

**Immediate send (< 1 second)**:
- Authentication codes
- Security alerts
- Transaction confirmations
- Error notifications

**Short delay (1-5 minutes)**:
- Batch related activities
- Aggregate similar events
- Wait for user to complete flow

**Scheduled send**:
- Digest emails (daily/weekly)
- Reminder notifications
- Scheduled reports
- Timezone-optimized sends

**Conditional delay**:
- Quiet hours respect
- Don't send if user active in app
- Wait for higher-priority notification to send first
- Delay until user completes related action

### Frequency rules

**Per-event notifications**:
- Security alerts
- Payment/transaction confirmations
- Critical system events
- User-initiated actions

**Batched notifications**:
- Social interactions (likes, comments)
- Multiple updates to same object
- Activity summaries
- Non-urgent system events

**Digest format**:
- Daily/weekly summaries
- Low-priority updates
- Historical data
- Cross-product updates

**Frequency caps**:
- Maximum per day by category
- Maximum per week for promotional content
- Escalating delays (1min, 5min, 15min, 1hr, 24hr)
- User-configurable limits

## Preference management rules

### Required preferences

**Global controls**:
- Master on/off switch per channel
- Quiet hours configuration
- Frequency preferences
- Language/locale settings

**Category controls**:
- Transactional (limited opt-out)
- System/security (required)
- Product updates (full control)
- Marketing (full control)
- Social/engagement (full control)

**Channel controls**:
- Enable/disable per channel per category
- Fallback channel preference
- Delivery timing preferences
- Format preferences (digest vs. real-time)

### Preference hierarchy
```
Global OFF → No notifications
↓
Category OFF → No notifications in that category
↓
Channel OFF → No notifications on that channel
↓
Quiet Hours → Delay until appropriate time
↓
Frequency Caps → Batch or delay additional notifications
↓
Send notification
```

## Error handling rules

### Retry strategy
**Hard failures (don't retry)**:
- Invalid email/phone number
- Unsubscribed user
- Blocked/bounced address
- Permission denied

**Soft failures (retry with backoff)**:
- Rate limit hit
- Temporary provider outage
- Network timeout
- Queue overflow

**Retry pattern**:
```
Attempt 1: Immediate
Attempt 2: 1 minute later
Attempt 3: 5 minutes later
Attempt 4: 15 minutes later
Attempt 5: 1 hour later
Give up after 5 attempts
```

### Fallback strategies

**Channel fallback**:
```
Primary: Push notification
If fails: Send email
If that fails: Log error, don't spam user
```

**Content fallback**:
```
Try: Full rich content
If fails: Plain text version
If fails: Minimal essential info
```

**Provider fallback**:
```
Primary: Provider A
If unavailable: Provider B
If unavailable: Queue for later retry
```

## Testing requirements

### Before launch checklist

**Technical tests**:
- [ ] Test across all target channels
- [ ] Verify variable substitution
- [ ] Check link functionality
- [ ] Test with missing data/variables
- [ ] Verify preference respect
- [ ] Check timing/scheduling
- [ ] Test batching logic
- [ ] Verify fallback behavior

**Content tests**:
- [ ] Proofread all copy
- [ ] Verify tone and voice
- [ ] Check for typos/grammar
- [ ] Test localization (if applicable)
- [ ] Verify brand consistency
- [ ] Check CTA clarity
- [ ] Test with real data

**User experience tests**:
- [ ] Verify mobile rendering
- [ ] Check desktop display
- [ ] Test notification center integration
- [ ] Verify read/unread states
- [ ] Check action button functionality
- [ ] Test deep linking
- [ ] Verify opt-out functionality

**Integration tests**:
- [ ] Test with actual providers
- [ ] Verify analytics tracking
- [ ] Check error monitoring
- [ ] Test rate limiting
- [ ] Verify queue processing
- [ ] Check database updates
- [ ] Test concurrent notifications

## Monitoring and alerts

### Key metrics to monitor

**Delivery metrics**:
- Delivery rate by channel
- Time to delivery (p50, p95, p99)
- Failure rate by error type
- Queue depth and lag
- Provider response times

**Engagement metrics**:
- Open rate by notification type
- Click-through rate by CTA
- Time to first interaction
- Completion rate for actions
- Unsubscribe rate by category

**System health**:
- API response times
- Queue processing rate
- Database query performance
- Provider uptime
- Error rate by type

**User satisfaction**:
- Preference change frequency
- Opt-out reasons
- Support ticket volume
- User feedback scores
- Re-engagement after opt-out

### Alert thresholds

**Critical (page immediately)**:
- Delivery rate drops below 95%
- Queue depth exceeds 10,000 messages
- Provider completely unavailable
- Authentication failures spiking
- Critical notification fails

**Warning (alert during business hours)**:
- Delivery rate drops below 98%
- Engagement rate drops 20%+
- Unsubscribe rate increases 50%+
- Queue processing lag > 5 minutes
- Error rate exceeds 5%

**Info (daily digest)**:
- Delivery trends
- Engagement patterns
- Volume changes
- New failure types
- Performance improvements

## Security and privacy rules

### Data handling

**Never include in notifications**:
- Full credit card numbers
- Social security numbers
- Passwords or tokens
- Unencrypted sensitive data
- Personally identifiable information (beyond name/email)

**Always include**:
- Unsubscribe link (for marketing)
- Preference management link
- Privacy policy link
- Data handling disclosure
- Support contact

### Compliance requirements

**CAN-SPAM (email)**:
- Include physical address
- Honor opt-out within 10 days
- Clear identification of sender
- Honest subject lines
- Mark promotional content

**TCPA (SMS)**:
- Obtain explicit consent
- Provide opt-out instructions
- Honor opt-out immediately
- Keep records of consent
- Don't use auto-dialer for marketing

**GDPR (EU users)**:
- Obtain explicit consent
- Provide data access
- Enable data deletion
- Maintain consent records
- Allow consent withdrawal

**CCPA (California)**:
- Disclose data collection
- Enable data deletion
- Allow opt-out of sale
- Provide data access
- Maintain privacy policy

## Documentation requirements

### Required documentation

**System design**:
- Architecture diagram
- Channel flow charts
- Preference logic
- Retry strategies
- Fallback patterns

**Notification catalog**:
- Complete notification list
- Trigger conditions
- Target audience
- Channel used
- Frequency expectations

**Templates**:
- Template registry
- Variable definitions
- Localization keys
- Sample outputs
- Version history

**Runbooks**:
- Common failure modes
- Debugging procedures
- Provider escalation
- Manual interventions
- Recovery procedures

**Style guide**:
- Copy guidelines
- Channel specifications
- Brand requirements
- Tone and voice
- Common patterns