---
title: "Notification System"
description: "Real-time notifications and push notification integration"
canonical: "https://docs.ainative.studio/docs/guides/notifications"
last-updated: "2026-10-03T21:47:10.764Z"
---

# Notification System

Source: https://docs.ainative.studio/docs/guides/notifications

> Real-time notifications and push notification integration

Complete guide to using the AINative Studio Notification System.

## Table of Contents

1. [Overview](#overview)
2. [Getting Started](#getting-started)
3. [Managing Notifications](#managing-notifications)
4. [Notification Preferences](#notification-preferences)
5. [Communication Settings](#communication-settings)
6. [Bulk Operations](#bulk-operations)
7. [Best Practices](#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

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

### Step 2: Check Unread Count

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

Response:
```json
{
  "count": 5
}
```

### Step 3: Read a Notification

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

```bash
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

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

#### Get Only Unread Notifications

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

#### Filter by Type

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

#### Pagination

```bash
## 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:

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

#### Manual Mark as Read

```bash
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

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

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

### Deleting Notifications

#### Delete Single Notification

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

#### Delete All Read Notifications

```bash
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

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

Response:
```json
{
  "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

```bash
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

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

Response:
```json
{
  "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

```bash
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:

```bash
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):
```json
{
  "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:

```bash
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:

```bash
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.

```python
## 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

```python
## 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:

```python
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

```python
## 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

```python
## Mark all as read efficiently
client.mark_all_as_read()

## Delete old read notifications
client.delete_all_read()
```

### 6. Handle Pagination Properly

```python
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

```python
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

```python
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

```python
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

```python
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:**
1. Check notification preferences are enabled
2. Verify email address is confirmed
3. Check spam folder
4. Ensure `email_frequency` is set to desired value

```bash
## 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:

```bash
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:**
1. Adjust notification preferences
2. Set email frequency to `daily` or `weekly`
3. Disable non-critical notifications

```python
## 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"
})
```

---

## Related Documentation

- [Quick Start Guide](/docs/getting-started/quick-start)
- [API Reference](/docs/api/overview)
- [Two-Factor Auth Guide](/docs/guides/two-factor-auth)
- [Error Codes](/docs/api/errors)

---

**Last Updated:** December 7, 2025
**Version:** 1.0