Notification System

Complete guide to using the AINative Studio Notification System.

Overview
Getting Started
Managing Notifications
Notification Preferences
Communication Settings
Bulk Operations
Best Practices

Overview

The AINative notification system provides:

In-App Notifications - View and manage notifications in your dashboard
Email Notifications - Receive important updates via email
Push Notifications - Get mobile/desktop push alerts (optional)
SMS Notifications - Receive critical alerts via text (optional)
Granular Preferences - Control what notifications you receive
Multi-Language Support - Notifications in 12 languages
Timezone Awareness - Notifications adjusted to your timezone

Notification Types

INFO (Blue) - General information and updates
SUCCESS (Green) - Successful operations and confirmations
WARNING (Yellow) - Important warnings that need attention
ERROR (Red) - Critical errors requiring immediate action

Getting Started

Step 1: View Your Notifications

curl -X GET "https://api.ainative.io/api/v1/notifications?limit=20&unread_only=true" \
  -H "Authorization: Bearer $TOKEN"

Step 2: Check Unread Count

curl -X GET https://api.ainative.io/api/v1/notifications/unread-count \
  -H "Authorization: Bearer $TOKEN"

Response:

{
  "count": 5
}

Step 3: Read a Notification

When you fetch a specific notification, it's automatically marked as read:

curl -X GET https://api.ainative.io/api/v1/notifications/123e4567-e89b-12d3-a456-426614174000 \
  -H "Authorization: Bearer $TOKEN"

Managing Notifications

Viewing Notifications

Get All Notifications

curl -X GET "https://api.ainative.io/api/v1/notifications?limit=50&offset=0" \
  -H "Authorization: Bearer $TOKEN"

Get Only Unread Notifications

curl -X GET "https://api.ainative.io/api/v1/notifications?unread_only=true" \
  -H "Authorization: Bearer $TOKEN"

Filter by Type

# Get only ERROR notifications
curl -X GET "https://api.ainative.io/api/v1/notifications?type=ERROR" \
  -H "Authorization: Bearer $TOKEN"

Pagination

# Page 1 (items 0-19)
curl -X GET "https://api.ainative.io/api/v1/notifications?limit=20&offset=0" \
  -H "Authorization: Bearer $TOKEN"

# Page 2 (items 20-39)
curl -X GET "https://api.ainative.io/api/v1/notifications?limit=20&offset=20" \
  -H "Authorization: Bearer $TOKEN"

Marking as Read

Auto-Mark on View

Simply fetching a notification marks it as read:

curl -X GET https://api.ainative.io/api/v1/notifications/{id} \
  -H "Authorization: Bearer $TOKEN"

Manual Mark as Read

curl -X PUT https://api.ainative.io/api/v1/notifications/{id} \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"read": true}'

Mark All as Read

curl -X POST https://api.ainative.io/api/v1/notifications/mark-all-read \
  -H "Authorization: Bearer $TOKEN"

Response:

{
  "success": true,
  "count": 12,
  "message": "Successfully marked 12 notifications as read"
}

Deleting Notifications

Delete Single Notification

curl -X DELETE https://api.ainative.io/api/v1/notifications/{id} \
  -H "Authorization: Bearer $TOKEN"

Delete All Read Notifications

curl -X DELETE https://api.ainative.io/api/v1/notifications/delete-all-read \
  -H "Authorization: Bearer $TOKEN"

Notification Preferences

Control which types of notifications you receive.

Get Current Preferences

curl -X GET https://api.ainative.io/api/v1/users/notification-preferences \
  -H "Authorization: Bearer $TOKEN"

Response:

{
  "user_id": "123e4567-e89b-12d3-a456-426614174000",
  "email_notifications": true,
  "push_notifications": false,
  "sms_notifications": false,
  "marketing_emails": false,
  "product_updates": true,
  "security_alerts": true,
  "created_at": "2025-12-07T10:00:00Z",
  "updated_at": "2025-12-07T10:00:00Z"
}

Update Preferences

curl -X PUT https://api.ainative.io/api/v1/users/notification-preferences \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "email_notifications": true,
    "push_notifications": true,
    "sms_notifications": false,
    "marketing_emails": false,
    "product_updates": true,
    "security_alerts": true
  }'

Preference Options

Preference	Description	Default
`email_notifications`	Receive all notifications via email	`true`
`push_notifications`	Browser/mobile push notifications	`false`
`sms_notifications`	Receive SMS for critical alerts	`false`
`marketing_emails`	Receive marketing and promotional emails	`false`
`product_updates`	New features and product announcements	`true`
`security_alerts`	Security-related notifications (recommended)	`true`

⚠️ Note: security_alerts should always be enabled for account security.

Communication Settings

Customize language, timezone, and email frequency.

Get Current Settings

curl -X GET https://api.ainative.io/api/v1/users/communication-settings \
  -H "Authorization: Bearer $TOKEN"

Response:

{
  "user_id": "550e8400-e29b-41d4-a716-446655440000",
  "language": "en",
  "timezone": "America/New_York",
  "email_frequency": "instant",
  "created_at": "2025-12-07T10:00:00Z",
  "updated_at": "2025-12-07T10:00:00Z"
}

Update Settings

curl -X PUT https://api.ainative.io/api/v1/users/communication-settings \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "language": "es",
    "timezone": "America/Los_Angeles",
    "email_frequency": "daily"
  }'

Supported Languages

en - English
es - Spanish (Español)
fr - French (Français)
de - German (Deutsch)
it - Italian (Italiano)
pt - Portuguese (Português)
ja - Japanese (日本語)
zh - Chinese (中文)
ko - Korean (한국어)
ru - Russian (Русский)
ar - Arabic (العربية)
hi - Hindi (हिन्दी)

Email Frequencies

instant - Send emails immediately (default)
daily - Daily digest at 9 AM in your timezone
weekly - Weekly digest on Monday at 9 AM

Example: If timezone is America/New_York and frequency is daily, you'll receive a digest at 9 AM EST/EDT every day.

Bulk Operations

Efficiently manage multiple notifications at once.

Bulk Create (Admin Only)

Create up to 100 notifications in one request:

curl -X POST https://api.ainative.io/api/v1/notifications/bulk/create \
  -H "Authorization: Bearer $ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "notifications": [
      {
        "user_id": "550e8400-e29b-41d4-a716-446655440000",
        "type": "INFO",
        "title": "Welcome",
        "message": "Welcome to AINative!",
        "action_url": "/dashboard"
      },
      {
        "user_id": "550e8400-e29b-41d4-a716-446655440000",
        "type": "SUCCESS",
        "title": "Setup Complete",
        "message": "Your account is ready."
      }
    ]
  }'

Response (Partial Success):

{
  "success": true,
  "success_count": 95,
  "failed_count": 5,
  "total_count": 100,
  "errors": [
    {"index": 3, "error": "User not found"},
    {"index": 12, "error": "Invalid notification type"}
  ],
  "message": "Successfully created 95 out of 100 notifications. 5 failed."
}

Bulk Mark as Read

Mark up to 100 notifications as read:

curl -X POST https://api.ainative.io/api/v1/notifications/bulk/mark-read \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "notification_ids": [
      "123e4567-e89b-12d3-a456-426614174000",
      "223e4567-e89b-12d3-a456-426614174001",
      "323e4567-e89b-12d3-a456-426614174002"
    ]
  }'

Bulk Delete

Delete up to 100 notifications:

curl -X POST https://api.ainative.io/api/v1/notifications/bulk/delete \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "notification_ids": [
      "123e4567-e89b-12d3-a456-426614174000",
      "223e4567-e89b-12d3-a456-426614174001"
    ]
  }'

Best Practices

1. Keep Unread Count Low

Regularly mark notifications as read or delete old notifications to maintain a clean inbox.

# Auto-mark as read after viewing
def view_notification(client, notif_id):
    notif = client.get_notification(notif_id)
    # Automatically marked as read!
    return notif

2. Use Filters Effectively

# Get only critical errors
errors = client.get_notifications(type="ERROR", unread_only=True)

# Process urgent items first
for notif in errors['notifications']:
    process_urgent_notification(notif)

3. Enable Security Alerts

Always keep security alerts enabled:

preferences = {
    "security_alerts": True,  # ALWAYS True
    "marketing_emails": False,
    "product_updates": True
}
client.update_preferences(preferences)

4. Set Appropriate Email Frequency

Instant - For time-sensitive work
Daily - For normal workflow
Weekly - For low-priority updates

# Set daily digest for better focus
settings = {
    "email_frequency": "daily",
    "timezone": "America/New_York"
}
client.update_communication_settings(settings)

5. Use Bulk Operations for Efficiency

# Mark all as read efficiently
client.mark_all_as_read()

# Delete old read notifications
client.delete_all_read()

6. Handle Pagination Properly

def fetch_all_notifications(client):
    """Fetch all notifications with pagination"""
    all_notifs = []
    offset = 0
    limit = 50

    while True:
        response = client.get_notifications(limit=limit, offset=offset)
        all_notifs.extend(response['notifications'])

        if not response['has_more']:
            break

        offset += limit

    return all_notifs

7. Respect Rate Limits

import time

def bulk_operation_with_retry(items, operation, batch_size=100):
    """Process items in batches with rate limit handling"""
    for i in range(0, len(items), batch_size):
        batch = items[i:i+batch_size]

        try:
            operation(batch)
        except RateLimitError as e:
            time.sleep(e.retry_after)
            operation(batch)  # Retry

Common Use Cases

Use Case 1: Daily Notification Cleanup

def daily_cleanup(client):
    """Mark all as read and delete old read notifications"""
    # Mark all as read
    result1 = client.mark_all_as_read()
    print(f"Marked {result1['count']} as read")

    # Delete all read
    result2 = client.delete_all_read()
    print(f"Deleted {result2['count']} old notifications")

Use Case 2: Priority Notification Handler

def handle_priority_notifications(client):
    """Process notifications by priority"""
    # Get all unread notifications
    notifs = client.get_notifications(unread_only=True)

    # Separate by type
    errors = [n for n in notifs['notifications'] if n['type'] == 'ERROR']
    warnings = [n for n in notifs['notifications'] if n['type'] == 'WARNING']
    info = [n for n in notifs['notifications'] if n['type'] == 'INFO']

    # Process in order of priority
    for notif in errors:
        handle_error(notif)

    for notif in warnings:
        handle_warning(notif)

    for notif in info:
        handle_info(notif)

Use Case 3: Multi-Language Support

def set_user_language(client, language_code):
    """Update user language preference"""
    client.update_communication_settings({
        "language": language_code
    })

# All future notifications will be in Spanish
set_user_language(client, "es")

Troubleshooting

Issue: Not Receiving Email Notifications

Solution:

Check notification preferences are enabled
Verify email address is confirmed
Check spam folder
Ensure email_frequency is set to desired value

# Verify preferences
curl -X GET https://api.ainative.io/api/v1/users/notification-preferences \
  -H "Authorization: Bearer $TOKEN"

Issue: Notifications Not in Preferred Language

Solution: Update communication settings:

curl -X PUT https://api.ainative.io/api/v1/users/communication-settings \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"language": "es"}'

Issue: Too Many Notifications

Solution:

Adjust notification preferences
Set email frequency to daily or weekly
Disable non-critical notifications

# Reduce notification volume
client.update_preferences({
    "marketing_emails": False,
    "product_updates": False,
    "security_alerts": True  # Keep security on!
})

client.update_communication_settings({
    "email_frequency": "daily"
})

Last Updated: December 7, 2025 Version: 1.0

Table of Contents​

Overview​

Notification Types​

Getting Started​

Step 1: View Your Notifications​

Step 2: Check Unread Count​

Step 3: Read a Notification​

Managing Notifications​

Viewing Notifications​

Get All Notifications​

Get Only Unread Notifications​

Filter by Type​

Pagination​

Marking as Read​

Auto-Mark on View​

Manual Mark as Read​

Mark All as Read​

Deleting Notifications​

Delete Single Notification​

Delete All Read Notifications​

Notification Preferences​

Get Current Preferences​

Update Preferences​

Preference Options​

Communication Settings​

Get Current Settings​

Update Settings​

Supported Languages​

Email Frequencies​

Bulk Operations​

Bulk Create (Admin Only)​

Bulk Mark as Read​

Bulk Delete​

Best Practices​

1. Keep Unread Count Low​

2. Use Filters Effectively​

3. Enable Security Alerts​

4. Set Appropriate Email Frequency​

5. Use Bulk Operations for Efficiency​

6. Handle Pagination Properly​

7. Respect Rate Limits​

Common Use Cases​

Use Case 1: Daily Notification Cleanup​

Use Case 2: Priority Notification Handler​

Use Case 3: Multi-Language Support​

Troubleshooting​

Issue: Not Receiving Email Notifications​

Issue: Notifications Not in Preferred Language​

Issue: Too Many Notifications​

Related Documentation​

Table of Contents

Overview

Notification Types

Getting Started

Step 1: View Your Notifications

Step 2: Check Unread Count

Step 3: Read a Notification

Managing Notifications

Viewing Notifications

Get All Notifications

Get Only Unread Notifications

Filter by Type

Pagination

Marking as Read

Auto-Mark on View

Manual Mark as Read

Mark All as Read

Deleting Notifications

Delete Single Notification

Delete All Read Notifications

Notification Preferences

Get Current Preferences

Update Preferences

Preference Options

Communication Settings

Get Current Settings

Update Settings

Supported Languages

Email Frequencies

Bulk Operations

Bulk Create (Admin Only)

Bulk Mark as Read

Bulk Delete

Best Practices

1. Keep Unread Count Low

2. Use Filters Effectively

3. Enable Security Alerts

4. Set Appropriate Email Frequency

5. Use Bulk Operations for Efficiency

6. Handle Pagination Properly

7. Respect Rate Limits

Common Use Cases

Use Case 1: Daily Notification Cleanup

Use Case 2: Priority Notification Handler

Use Case 3: Multi-Language Support

Troubleshooting

Issue: Not Receiving Email Notifications

Issue: Notifications Not in Preferred Language

Issue: Too Many Notifications

Related Documentation