Constructive Notifications
Multi-channel notification system with inbox, delivery tracking, bounce/complaint handling, address suppression, and digest batching.
Use the Notifications feature pack through constructive-blocks for the tenant inbox UI. Its standalone view renders host-supplied inbox resources and actions. Its Console module requires an explicit reachable notifications endpoint whose introspection exposes the required operations, so installation alone does not prove Console availability.
The current Blocks view and Console adapter expose inbox resources plus
read-state actions only. Discovery may report notifications.settings when
Query.notificationPreferences exists, but that evidence does not create a
rendered settings route, preferences form, or settings adapter. Build a custom
settings surface against the domain contract when the product needs one, and
do not present that surface as part of the installed Notifications block.
When to Apply
Use this skill when:
- Adding notifications to a Constructive app
- Configuring notification channels (email, push, SMS, webhook)
- Setting up bounce/complaint webhook handlers (SES, SendGrid, Twilio)
- Working with the suppression list (blocking sends to hard-bounced/complained addresses)
- Implementing notification preferences, quiet hours, or digest batching
- Debugging delivery failures or channel deactivation
- Understanding the notification table graph and delivery lifecycle
Module Setup
The current full backend profile includes notifications. For a custom backend composition, add notifications_module through the supported Constructive DB provisioning mechanism; do not reconstruct a preset's module array in application code.
Feature Flags
Control which sub-features are generated (zero dead code when off):
| Flag |
Default |
What it gates |
has_channels |
true |
Device endpoints, delivery log, suppression list |
has_preferences |
true |
Per-user channel toggles by category/topic |
has_settings_extension |
false |
Quiet hours, digest frequency, master switch on user/org settings |
has_digest_metadata |
false |
Group collapsing, digest buckets, deliver_after scheduling |
has_subscriptions |
false |
(reserved for future topic subscription table) |
Table Graph
notifications_module (config)
├── notifications (public, RLS: AuthzComposite)
│ └── notification_read_state (public, RLS: AuthzDirectOwner)
├── notification_preferences (public, RLS: AuthzDirectOwner) [has_preferences]
├── notification_channels (public, RLS: AuthzDirectOwner) [has_channels]
├── notification_delivery_log (private, no RLS) [has_channels]
└── notification_suppressions (private, no RLS) [has_channels]
Public tables are exposed via GraphQL with RLS. Private tables (delivery log and suppressions) are internal; delivery workers and webhook handlers must use their supported backend service surface rather than application GraphQL or direct table access.
Delivery Status Lifecycle
pending → sent → delivered
→ bounced (async webhook, hard/soft bounce)
→ complained (async webhook, recipient marked as spam)
→ failed (immediate failure)
→ throttled (rate-limited by provider)
→ grouped (collapsed into digest)
Key distinction: bounced (mailbox doesn't exist) and complained (recipient clicked "Report Spam") are different signals requiring different responses. Both create suppression entries, but complaint rates > 0.1% trigger ISP penalties.
References
| File |
Content |
| deliverability.md |
Webhook setup (SES/SendGrid/Twilio), suppression management, channel deactivation, monitoring queries |
| tables.md |
All 6 tables with columns, types, defaults, and descriptions |
Cross-References
1---2name: constructive-notifications3description: Notification system — inbox, delivery, channels, preferences, bounce/complaint handling, suppression list, and digest batching. Use when asked to 'add notifications', 'notification preferences', 'bounce handling', 'complaint handling', 'suppression list', 'delivery log', 'notification channels', 'digest batching', 'quiet hours', 'webhook ingestion', 'SES bounces', 'SendGrid webhooks', 'channel deactivation', or when working with notifications_module in blueprints.4---56# Constructive Notifications78Multi-channel notification system with inbox, delivery tracking, bounce/complaint handling, address suppression, and digest batching.910Use the Notifications feature pack through [`constructive-blocks`](../constructive-blocks/SKILL.md) for the tenant inbox UI. Its standalone view renders host-supplied inbox resources and actions. Its Console module requires an explicit reachable `notifications` endpoint whose introspection exposes the required operations, so installation alone does not prove Console availability.1112The current Blocks view and Console adapter expose inbox resources plus13read-state actions only. Discovery may report `notifications.settings` when14`Query.notificationPreferences` exists, but that evidence does not create a15rendered settings route, preferences form, or settings adapter. Build a custom16settings surface against the domain contract when the product needs one, and17do not present that surface as part of the installed Notifications block.1819## When to Apply2021Use this skill when:22- Adding notifications to a Constructive app23- Configuring notification channels (email, push, SMS, webhook)24- Setting up bounce/complaint webhook handlers (SES, SendGrid, Twilio)25- Working with the suppression list (blocking sends to hard-bounced/complained addresses)26- Implementing notification preferences, quiet hours, or digest batching27- Debugging delivery failures or channel deactivation28- Understanding the notification table graph and delivery lifecycle2930## Module Setup3132The current `full` backend profile includes notifications. For a custom backend composition, add `notifications_module` through the supported Constructive DB provisioning mechanism; do not reconstruct a preset's module array in application code.3334### Feature Flags3536Control which sub-features are generated (zero dead code when off):3738| Flag | Default | What it gates |39|------|---------|---------------|40| `has_channels` | `true` | Device endpoints, delivery log, suppression list |41| `has_preferences` | `true` | Per-user channel toggles by category/topic |42| `has_settings_extension` | `false` | Quiet hours, digest frequency, master switch on user/org settings |43| `has_digest_metadata` | `false` | Group collapsing, digest buckets, deliver_after scheduling |44| `has_subscriptions` | `false` | *(reserved for future topic subscription table)* |4546## Table Graph4748```49notifications_module (config)50├── notifications (public, RLS: AuthzComposite)51│ └── notification_read_state (public, RLS: AuthzDirectOwner)52├── notification_preferences (public, RLS: AuthzDirectOwner) [has_preferences]53├── notification_channels (public, RLS: AuthzDirectOwner) [has_channels]54├── notification_delivery_log (private, no RLS) [has_channels]55└── notification_suppressions (private, no RLS) [has_channels]56```5758**Public tables** are exposed via GraphQL with RLS. **Private tables** (delivery log and suppressions) are internal; delivery workers and webhook handlers must use their supported backend service surface rather than application GraphQL or direct table access.5960## Delivery Status Lifecycle6162```63pending → sent → delivered64 → bounced (async webhook, hard/soft bounce)65 → complained (async webhook, recipient marked as spam)66 → failed (immediate failure)67 → throttled (rate-limited by provider)68→ grouped (collapsed into digest)69```7071Key distinction: **bounced** (mailbox doesn't exist) and **complained** (recipient clicked "Report Spam") are different signals requiring different responses. Both create suppression entries, but complaint rates > 0.1% trigger ISP penalties.7273## References7475| File | Content |76|------|---------|77| [deliverability.md](./references/deliverability.md) | Webhook setup (SES/SendGrid/Twilio), suppression management, channel deactivation, monitoring queries |78| [tables.md](./references/tables.md) | All 6 tables with columns, types, defaults, and descriptions |7980## Cross-References8182- **SQL-level generator internals:** `constructive-db-notifications` skill in constructive-db83- **Realtime subscriptions (separate system):** [`constructive-realtime`](../constructive-realtime/SKILL.md)84- **Background job triggers:** [`constructive-jobs`](../constructive-jobs/SKILL.md)85- **Billing/limits for rate caps:** [`constructive-billing`](../constructive-billing/SKILL.md)86- **Notifications feature-pack UI:** [`constructive-blocks`](../constructive-blocks/SKILL.md)
constructive-io