Notifications API

Send and manage notifications via email, SMS, and other channels

Overview

The Notifications API allows you to send notifications through various channels and track their delivery status. Perfect for automated emails, alerts, and communication workflows.

Supported Channels

Email
SMS (planned)
Push notifications (planned)

Features

Smart email templates with type-specific formatting
Priority indicators (urgent, high, normal, low)
Status change visualizations
Message sender tracking
Delivery tracking
Read/unread status tracking
Notification counts and statistics
Action buttons
Batch operations

Method	Endpoint	Description	Requirements
Sending Notifications
POST	/api/notifications/send	Send a notification via specified channel	`channel (required) – notification channel: "email"` `recipient_email (required) – recipient email address` `subject (required) – notification subject line` `payload (required) – notification content and data`
Retrieving Notifications
GET	/api/notifications/list/all	Get a list of notifications for a recipient	`recipient_email (required) – recipient email address` `status (optional) – filter by status: pending, sent, failed` `unread_only (optional) – show only unread notifications (true/false)` `limit (optional) – limit results (1-100, default: 20)`
GET	/api/notifications/count/stats	Get notification counts and statistics for a recipient	`recipient_email (required) – recipient email address`
GET	/api/notifications/{id}	Retrieve notification status and delivery information	`id (required) – Notification ID from send response`
Read Status Management
POST	/api/notifications/{id}/read	Mark a single notification as read	`id (required) – Notification ID`
POST	/api/notifications/{id}/unread	Mark a single notification as unread	`id (required) – Notification ID`
POST	/api/notifications/read-all	Mark all notifications as read for a recipient	`recipient_email (required) – recipient email address`

Request Examples

Supported Notification Types

💬 message - Chat/inbox messages

🔄 status_change - Status updates

📦 order - Order notifications

✅ task - Task assignments

⏰ reminder - Scheduled reminders

🔔 alert - System alerts

Each type automatically applies appropriate icons, formatting, and special features.

Send Message Notification

POST /api/notifications/send

"channel": "email", "recipient_email": "user@example.com", "subject": "New Message from John Doe", "payload": { "type": "message", "title": "New Message", "content": "You have received a new message in your inbox.", "priority": "normal", "metadata": { "sender": "John Doe", "sent_at": "2025-10-30T10:30:00Z" }, "action_url": "https://example.com/messages/123", "action_text": "Read Message" }

Send Status Change Notification

POST /api/notifications/send

"channel": "email", "recipient_email": "customer@example.com", "subject": "Order Status Updated", "payload": { "type": "status_change", "title": "Order #12345 Status Update", "content": "Your order status has been updated.", "priority": "high", "metadata": { "old_status": "processing", "new_status": "shipped", "order_id": "12345" }, "action_url": "https://example.com/orders/12345", "action_text": "Track Order" }

Send Alert Notification

POST /api/notifications/send

"channel": "email", "recipient_email": "admin@example.com", "subject": "System Maintenance Alert", "payload": { "type": "alert", "title": "Scheduled Maintenance", "content": "System maintenance will begin tonight at 11 PM.", "priority": "urgent", "metadata": { "maintenance_start": "2025-10-30T23:00:00Z", "estimated_duration": "2 hours", "system": "main_database" } }

Response

{ "status": "success", "notification_id": "notif_abc123def456", "message": "Notification queued for delivery", "estimated_delivery": "2024-10-09T15:30:00Z" }

Check Notification Status

GET /api/notifications/notif_abc123def456

{ "id": "notif_abc123def456", "status": "delivered", "channel": "email", "recipient": "user@example.com", "sent_at": "2024-10-09T15:32:15Z", "delivered_at": "2024-10-09T15:32:18Z" }

List Notifications

GET /api/notifications/list/all?recipient_email=customer@example.com&unread_only=true&limit=10

{ "status": "success", "data": { "notifications": [ { "id": "notif_abc123", "channel": "email", "recipient_email": "customer@example.com", "subject": "New Message Received", "status": "sent", "is_read": false, "read_at": null, "sent_at": "2025-11-13T14:30:00Z", "created_at": "2025-11-13T14:30:00Z" } ], "total": 12, "filters": { "recipient_email": "customer@example.com", "unread_only": true, "limit": 10 } } }

Get Notification Counts & Statistics

GET /api/notifications/count/stats?recipient_email=customer@example.com

{ "status": "success", "data": { "recipient_email": "customer@example.com", "total": 45, "unread": 12, "read": 33, "by_status": { "pending": 2, "sent": 42, "failed": 1 }, "recent_unread": [ { "id": "notif_abc123", "subject": "New Message Received", "sent_at": "2025-11-13T14:30:00Z" } ] } }

Mark Notification as Read

POST /api/notifications/notif_abc123/read

{ "status": "success", "message": "Notification marked as read", "notification": { "id": "notif_abc123", "is_read": true, "read_at": "2025-11-13T15:00:00Z" } }

Mark All Notifications as Read

POST /api/notifications/read-all

Request Body:

{ "recipient_email": "customer@example.com" }

Response:

{ "status": "success", "message": "All notifications marked as read", "updated_count": 12 }