Notifications Rail

Notifications Rail

Multi-channel notification delivery.

Overview

The Notifications Rail provides endpoints for sending notifications across multiple channels including email, SMS, push, and in-app.

Base URL

/api/v1/notifications

Endpoints

Send Notification

POST /api/v1/notifications

Send a notification.

Request Body:

{
  "recipientId": "user_123",
  "templateId": "contract_approved",
  "channels": ["EMAIL", "PUSH"],
  "data": {
    "contractId": "con_abc",
    "contractType": "MURABAHA",
    "amount": "500000.00",
    "currency": "SAR"
  },
  "priority": "HIGH",
  "scheduledAt": null
}

Response:

{
  "data": {
    "notificationId": "notif_abc123",
    "status": "QUEUED",
    "channels": [
      { "channel": "EMAIL", "status": "QUEUED" },
      { "channel": "PUSH", "status": "QUEUED" }
    ],
    "createdAt": "2025-01-15T10:00:00Z"
  }
}

Send Bulk Notification

POST /api/v1/notifications/bulk

Send notifications to multiple recipients.

Request Body:

{
  "templateId": "maintenance_notice",
  "recipientQuery": {
    "roles": ["customer"],
    "tenantId": "tenant_123"
  },
  "channels": ["EMAIL"],
  "data": {
    "maintenanceDate": "2025-01-20",
    "duration": "2 hours"
  },
  "priority": "NORMAL"
}

Get Notification

GET /api/v1/notifications/:notificationId

Get notification status.

Response:

{
  "data": {
    "notificationId": "notif_abc123",
    "recipientId": "user_123",
    "templateId": "contract_approved",
    "status": "DELIVERED",
    "channels": [
      {
        "channel": "EMAIL",
        "status": "DELIVERED",
        "deliveredAt": "2025-01-15T10:00:05Z"
      },
      {
        "channel": "PUSH",
        "status": "DELIVERED",
        "deliveredAt": "2025-01-15T10:00:02Z"
      }
    ]
  }
}

List Notifications

GET /api/v1/notifications

List notifications.

Query Parameters:

Parameter	Type	Description
recipientId	string	Filter by recipient
status	string	Filter by status
channel	string	Filter by channel
from	string	Start date

Create Template

POST /api/v1/notifications/templates

Create a notification template.

Request Body:

{
  "id": "contract_approved",
  "name": "Contract Approved",
  "channels": {
    "email": {
      "subject": "Your {{contractType}} contract has been approved",
      "body": "Dear {{recipientName}},\n\nYour contract #{{contractId}} for {{amount}} {{currency}} has been approved.",
      "fromName": "Islamic Open Finance"
    },
    "push": {
      "title": "Contract Approved",
      "body": "Your {{contractType}} contract has been approved!"
    },
    "sms": {
      "body": "IOF: Your contract #{{contractId}} has been approved."
    }
  },
  "defaultChannel": "EMAIL"
}

List Templates

GET /api/v1/notifications/templates

List notification templates.

Get User Preferences

GET /api/v1/notifications/preferences/:userId

Get user notification preferences.

Response:

{
  "data": {
    "userId": "user_123",
    "preferences": {
      "contract_approved": ["EMAIL", "PUSH"],
      "payment_reminder": ["EMAIL", "SMS"],
      "marketing": []
    },
    "globalOptOut": false,
    "quietHours": {
      "enabled": true,
      "start": "22:00",
      "end": "08:00",
      "timezone": "Asia/Riyadh"
    }
  }
}

Update Preferences

PATCH /api/v1/notifications/preferences/:userId

Update notification preferences.

Request Body:

{
  "preferences": {
    "marketing": ["EMAIL"]
  },
  "quietHours": {
    "enabled": true,
    "start": "23:00",
    "end": "07:00"
  }
}

Channels

Channel	Description
EMAIL	Email notification
SMS	SMS message
PUSH	Mobile push notification
IN_APP	In-app notification
WEBHOOK	Webhook delivery

Notification Status

Status	Description
QUEUED	Queued for delivery
SENDING	Being sent
DELIVERED	Successfully delivered
FAILED	Delivery failed
BOUNCED	Email bounced
UNSUBSCRIBED	User unsubscribed

Priority Levels

Priority	Description
CRITICAL	Immediate delivery
HIGH	High priority
NORMAL	Normal priority
LOW	Low priority

Events

Event	Description
notification.sent	Notification sent
notification.delivered	Notification delivered
notification.failed	Delivery failed
notification.opened	Notification opened
notification.clicked	Link clicked

See Also

• Events Rail - Event distribution
• Webhooks Rail - Webhook delivery