Skip to content

Notifications API

The Notifications API manages user notification preferences, delivery history, and email service health. It supports multiple notification types including new match alerts, deadline reminders, weekly digests, and application status changes.

All endpoints require authentication and are scoped to the current user.

Notification Types

Type Description
new_match Alert when new grant matches are found
deadline_reminder Reminder for upcoming grant deadlines
weekly_digest Weekly summary of matches and deadlines
welcome Welcome email sent after registration
application_status Notification when application status changes
test Test email for verifying configuration

Delivery Statuses

Status Description
pending Notification queued for delivery
sent Email sent to provider
delivered Delivery confirmed by provider
bounced Email bounced (invalid address)
failed Delivery failed (provider error)

Notification Preferences

GET /notifications/preferences

Get the current user's notification preferences. Creates default preferences if none exist.

Authentication: Required

{
  "id": "n1a2b3c4-d5e6-7890-abcd-ef1234567890",
  "user_id": "550e8400-e29b-41d4-a716-446655440000",
  "email_notifications_enabled": true,
  "notification_frequency": "immediate",
  "new_match_notifications": true,
  "match_threshold": 70,
  "deadline_notifications": true,
  "deadline_reminder_days": [7, 3, 1],
  "weekly_digest_enabled": true,
  "weekly_digest_day": 1,
  "application_status_notifications": true,
  "created_at": "2025-01-15T10:30:00Z",
  "updated_at": "2025-01-15T10:30:00Z"
}

curl -X GET https://api.carbonconnect.io/api/v1/notifications/preferences \
  -H "Authorization: Bearer <token>"

PATCH /notifications/preferences

Update notification preferences. Only provided fields are updated.

Authentication: Required

{
  "match_threshold": 80,
  "deadline_reminder_days": [14, 7, 3],
  "weekly_digest_enabled": false,
  "notification_frequency": "daily"
}

{
  "id": "n1a2b3c4-d5e6-7890-abcd-ef1234567890",
  "user_id": "550e8400-e29b-41d4-a716-446655440000",
  "email_notifications_enabled": true,
  "notification_frequency": "daily",
  "new_match_notifications": true,
  "match_threshold": 80,
  "deadline_notifications": true,
  "deadline_reminder_days": [14, 7, 3],
  "weekly_digest_enabled": false,
  "weekly_digest_day": 1,
  "application_status_notifications": true,
  "created_at": "2025-01-15T10:30:00Z",
  "updated_at": "2025-01-16T09:00:00Z"
}

curl -X PATCH https://api.carbonconnect.io/api/v1/notifications/preferences \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"match_threshold": 80, "weekly_digest_enabled": false}'

Request Body (NotificationPreferencesUpdate):

Field Type Description
email_notifications_enabled boolean Master switch for all email notifications
notification_frequency string Frequency: immediate, daily, weekly
new_match_notifications boolean Enable new match alerts
match_threshold integer Minimum match score to trigger notification (0-100)
deadline_notifications boolean Enable deadline reminders
deadline_reminder_days int[] Days before deadline to send reminders (0-30 each)
weekly_digest_enabled boolean Enable weekly digest emails
weekly_digest_day integer Day of week for digest (0=Sunday, 1=Monday, ... 6=Saturday)
application_status_notifications boolean Enable application status change alerts

Reminder Days Validation

The deadline_reminder_days array must contain at least one value. Values must be between 0 and 30. Duplicates are automatically removed and values are sorted in descending order.

PUT /notifications/preferences

Replace notification preferences (full update). Functionally identical to PATCH, included for REST completeness.

Authentication: Required

Notification History

GET /notifications/history

Get paginated notification history for the current user with optional filtering.

Authentication: Required

{
  "items": [
    {
      "id": "h1a2b3c4-d5e6-7890-abcd-ef1234567890",
      "user_id": "550e8400-e29b-41d4-a716-446655440000",
      "notification_type": "new_match",
      "email_subject": "3 New Grant Matches Found",
      "email_to": "user@example.com",
      "email_template": "new_match",
      "status": "delivered",
      "grant_id": "b1c2d3e4-f5a6-7890-bcde-f12345678901",
      "match_id": "d4e5f6a7-b8c9-0123-def0-456789012345",
      "sent_at": "2025-01-15T10:30:00Z",
      "delivered_at": "2025-01-15T10:30:05Z",
      "message_id": "ses-msg-12345",
      "created_at": "2025-01-15T10:30:00Z"
    }
  ],
  "total": 25,
  "page": 1,
  "page_size": 20,
  "total_pages": 2
}

curl -X GET "https://api.carbonconnect.io/api/v1/notifications/history?notification_type=new_match&status=delivered&page=1" \
  -H "Authorization: Bearer <token>"

Query Parameters:

Parameter Type Default Description
notification_type string -- Filter by type (see Notification Types)
status string -- Filter by delivery status
page integer 1 Page number
page_size integer 20 Items per page (1-100)

Response Body (NotificationHistoryListResponse):

Field Type Description
items array Notification records
total integer Total matching records
page integer Current page
page_size integer Page size
total_pages integer Total pages

GET /notifications/history/{notification_id}

Get details of a specific notification. Only returns notifications belonging to the current user.

Authentication: Required

curl -X GET https://api.carbonconnect.io/api/v1/notifications/history/h1a2b3c4-d5e6-7890-abcd-ef1234567890 \
  -H "Authorization: Bearer <token>"

Path Parameters:

Parameter Type Description
notification_id string Notification ID (UUID format)

Status Codes:

Code Description
200 Notification returned
400 Invalid notification ID format
401 Not authenticated
404 Notification not found or belongs to other user

Test Email

POST /notifications/test

Send a test email to verify that notification delivery is working correctly.

Authentication: Required

{
  "email_type": "test",
  "custom_subject": "Carbon Connect Test Email"
}

{
  "success": true,
  "message": "Test email sent successfully to user@example.com",
  "message_id": "ses-msg-test-67890"
}

curl -X POST https://api.carbonconnect.io/api/v1/notifications/test \
  -H "Authorization: Bearer <token>"

Request Body (optional):

Field Type Required Description
email_type string No Notification type (default: test)
custom_subject string No Custom email subject line

Response Body:

Field Type Description
success boolean Whether the email was sent successfully
message string Human-readable status message
message_id string Provider message ID (null on failure)

Status Codes:

Code Description
200 Test result returned
401 Not authenticated
500 Email service error

Notification Statistics

GET /notifications/stats

Get notification statistics for the current user, broken down by type and delivery status.

Authentication: Required

{
  "total_notifications": 125,
  "notifications_last_7_days": 8,
  "by_type": {
    "new_match": 45,
    "deadline_reminder": 30,
    "weekly_digest": 12,
    "application_status": 38
  },
  "by_status": {
    "delivered": 110,
    "sent": 10,
    "bounced": 2,
    "failed": 3
  }
}

curl -X GET https://api.carbonconnect.io/api/v1/notifications/stats \
  -H "Authorization: Bearer <token>"

Response Body:

Field Type Description
total_notifications integer Total notifications ever sent
notifications_last_7_days integer Notifications sent in the past 7 days
by_type object Count per notification type
by_status object Count per delivery status

Email Service Health

GET /notifications/health

Check the health status of the email delivery service. Returns backend configuration and rate limit usage.

Authentication: Required

{
  "status": "healthy",
  "backend": "ses",
  "rate_limit": "15/100"
}

curl -X GET https://api.carbonconnect.io/api/v1/notifications/health \
  -H "Authorization: Bearer <token>"

Response Body:

Field Type Description
status string Health status: healthy, degraded, unavailable
backend string Email backend provider (e.g., ses)
rate_limit string Current rate limit usage

Degraded Status

A degraded status indicates the email service is responding but with elevated error rates. An unavailable status means the service cannot be reached.