Notification System

Test Notification - /api/notifications/test

• Endpoint: /api/notifications/test
• Method: POST
• Description: Send test notifications (simple, template-based, or email) to verify notification configuration.
• Authentication: Requires administrator session and CSRF token
• Request Body: For simple test:

  {
    "type": "simple",
    "ntfyConfig": {
      "url": "https://ntfy.sh",
      "topic": "test-topic",
      "accessToken": "optional-access-token"
    }
  }

  For template test:

  {
    "type": "template",
    "ntfyConfig": {
      "url": "https://ntfy.sh",
      "topic": "test-topic",
      "accessToken": "optional-access-token"
    },
    "template": {
      "title": "Test Title",
      "message": "Test message with {variable}",
      "priority": "default",
      "tags": "test"
    }
  }

  For email test:

  {
    "type": "email"
  }

• Response: For simple test:

  {
    "message": "Test notification sent successfully"
  }

  For template test:

  {
    "success": true,
    "message": "Test notifications sent successfully via NTFY and Email",
    "channels": ["NTFY", "Email"]
  }

  For email test:

  {
    "message": "Test email sent successfully"
  }

  The test email content displays:
  • SMTP server hostname and port
  • Connection type (Plain SMTP, STARTTLS, or Direct SSL/TLS)
  • SMTP authentication requirement status
  • SMTP username (only shown when authentication is required)
  • Recipient email address
  • From address and sender name used for the email
  • Test timestamp
• Error Responses:
  • 401: Unauthorized - Invalid session or CSRF token
  • 400: NTFY configuration is required, invalid configuration, or email not configured
  • 500: Failed to send test notification with error details
• Notes:
  • Supports simple test messages, template-based notifications, and email tests
  • Template testing uses sample data to replace template variables
  • Includes timestamp in the test message
  • NTFY tests use the stored NTFY configuration; a client-supplied NTFY URL is not used
  • Uses accessToken field for authentication when stored
  • For template tests, sends notifications to both NTFY and email (if configured)
  • Email tests require SMTP configuration to be set up
  • The test email endpoint clears the request cache before reading SMTP configuration, ensuring that external scripts can update the configuration and have it immediately reflected in test emails
  • Template tests and Daily Summary send-now bypass per-backup suppression

Preview Notification Template - /api/notifications/preview

• Endpoint: /api/notifications/preview
• Method: POST
• Description: Renders a notification template with the production Markdown renderer without sending. Body includes kind (success, warning, overdueBackup, or dailySummaryEmail) and the template being edited. Daily Summary previews use the current real snapshot; other kinds use deterministic sample values. Email HTML is intended for a sandboxed iframe. Success, Warning/Error, and Overdue also return the NTFY payload (ntfyMessage); any GFM table header is omitted and body rows are plain text.
• Authentication: Requires valid session and CSRF token

Check Overdue Backups - /api/notifications/check-overdue

• Endpoint: /api/notifications/check-overdue
• Method: POST
• Description: Manually triggers the overdue backup check and sends notifications.
• Authentication: Requires valid session and CSRF token
• Response:

  {
    "message": "Overdue backup check completed",
    "statistics": {
      "totalBackupConfigs": 5,
      "checkedBackups": 5,
      "overdueBackupsFound": 2,
      "notificationsSent": 2
    }
  }

• Error Responses:
  • 500: Failed to check for overdue backups
• Notes:
  • Manually triggers overdue backup check
  • Returns statistics about the check process
  • Sends notifications for overdue backups found

Notification Channel Alerts - /api/notification-channel-alerts

• Endpoint: /api/notification-channel-alerts
• Method: GET, POST
• Description: Lists open email and ntfy delivery failures for the signed-in administrator, or clears the listed channels until a newer failure is logged.
• Authentication: Requires an administrator session. POST also requires a CSRF token in the X-CSRF-Token header.
• Request Body (POST):

  {
    "channels": ["email", "ntfy"]
  }

  channels must contain one or both of email and ntfy.
• Response:

  {
    "alerts": [
      {
        "channel": "email",
        "error": "SMTP authentication failed",
        "latestTimestamp": "2026-09-23 22:10:00",
        "failureCount": 3,
        "settingsTab": "email",
        "host": "smtp.gmail.com"
      }
    ]
  }

  Each alert includes channel, error (at most 500 characters), latestTimestamp, failureCount, and settingsTab (email or ntfy). Email alerts may include host. NTFY alerts may include topic.
• Error Responses:
  • 400 INVALID_CONFIGURATION: POST body is missing, or channels is empty or contains an unknown value
  • 500 INTERNAL_ERROR: Failed to read or clear the alerts
• Notes:
  • GET returns the channels that are still failing for this administrator
  • POST records a per-administrator clear for each listed channel that is currently open, then returns the remaining alerts
  • A later failure shows the channel again, even when the error text is unchanged
  • A later successful delivery for that channel keeps it hidden
  • The clear marker is stored in configuration and does not include secrets

Clear Overdue Timestamps - /api/notifications/clear-overdue-timestamps

• Endpoint: /api/notifications/clear-overdue-timestamps
• Method: POST
• Description: Clears all overdue backup notification timestamps, allowing notifications to be sent again.
• Authentication: Requires valid session and CSRF token
• Response:

  {
    "message": "Overdue backup notification timestamps cleared successfully"
  }

• Error Responses:
  • 500: Failed to clear overdue backup timestamps
• Notes:
  • Clears all overdue backup notification timestamps
  • Allows notifications to be sent again
  • Useful for testing notification system