Sending Notifications

The NotificationController at /api/v1/notifications provides endpoints for sending, retrieving, retrying, and cancelling notifications.

Send a Notification

Endpoint: POST /api/v1/notifications

curl -X POST http://localhost:8085/api/v1/notifications \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ${TOKEN}" \
  -d '{
    "tenantId": "550e8400-e29b-41d4-a716-446655440000",
    "userId": "user-001",
    "channel": "EMAIL",
    "templateKey": "welcome-email",
    "recipient": "alice@acme.com",
    "subject": "Welcome to MATIH",
    "variables": {
      "userName": "Alice",
      "dashboardUrl": "https://acme.matih.ai/dashboard",
      "trialDays": 14
    },
    "priority": "NORMAL",
    "metadata": {
      "source": "onboarding",
      "correlationId": "onb-123"
    }
  }'

Response (201 Created):

{
  "id": "notif-001",
  "tenantId": "550e8400-...",
  "userId": "user-001",
  "channel": "EMAIL",
  "recipient": "alice@acme.com",
  "subject": "Welcome to MATIH",
  "status": "PENDING",
  "priority": "NORMAL",
  "createdAt": "2026-02-12T10:00:00Z"
}

Get Notification by ID

Endpoint: GET /api/v1/notifications/{id}

curl http://localhost:8085/api/v1/notifications/notif-001 \
  -H "Authorization: Bearer ${TOKEN}"

List Tenant Notifications

Endpoint: GET /api/v1/notifications/tenant/{tenantId}

curl "http://localhost:8085/api/v1/notifications/tenant/550e8400-e29b-41d4-a716-446655440000?page=0&size=20" \
  -H "Authorization: Bearer ${TOKEN}"

List User Notifications

Endpoint: GET /api/v1/notifications/tenant/{tenantId}/user/{userId}

Retry a Failed Notification

Re-attempt delivery of a failed notification.

Endpoint: POST /api/v1/notifications/{id}/retry

curl -X POST http://localhost:8085/api/v1/notifications/notif-001/retry \
  -H "Authorization: Bearer ${TOKEN}"

Cancel a Pending Notification

Cancel a notification that has not yet been delivered.

Endpoint: POST /api/v1/notifications/{id}/cancel

curl -X POST http://localhost:8085/api/v1/notifications/notif-001/cancel \
  -H "Authorization: Bearer ${TOKEN}"

Only notifications in PENDING or QUEUED status can be cancelled. Notifications that are already SENDING or DELIVERED cannot be cancelled.

Architecture Templates