Messaging

Overview

The Infomaxim Messaging API provides robust email and push notification capabilities for your applications. All notifications are template-based and controlled through admin panel settings, ensuring consistency and security across your platform.

Key Features

• Template-Based Notifications: Define reusable email templates in the admin panel
• Event-Driven: Trigger notifications based on specific events (order confirmation, password reset, etc.)
• Data Merging: Automatically merge dynamic data into email templates
• Admin Controls: Enable/disable notifications and configure default email settings
• Notification Logging: Track all sent notifications in aurora_notification_log
• Record Linking: Associate notifications with specific database records
• Push Notifications: Support for web push notifications via VAPID protocol

Database Tables

• aurora_notifications

  Stores notification templates with event names, subject lines, and HTML content.

• aurora_notification_log

  Logs all notification attempts with status tracking (Pending, Sent, Failed).

• aurora_related

  Links notifications to specific database records (e.g., orders, customers).

• aurora_sites

  Contains application-level email settings (disable_email, email_from, email_cc, email_bcc).

Messaging

The messaging API provides email and push notification capabilities with integration to SendGrid and custom push notification services.

POST/message/notification

Sends an email notification based on predefined notification templates configured in the admin panel.

Authentication

Required Header:

site-id: YOUR_APP_ID
or
x-site-id: YOUR_APP_ID

The application ID is automatically inherited from the header and cannot be forced through the request body.

Request Body

{
  "event": "order-confirmation",
  "email": "customer@example.com",
  "table": "aurora_orders",
  "master_id": 12345,
  "data": {
    "orderNumber": "ORD-2024-5001",
    "customerName": "John Doe",
    "total": "$999.97"
  },
  "setEmailField": "customer_email"
}

Parameters

• event string required

  The notification event name. Must match an enabled event in the aurora_notifications table. Common events include: order-confirmation, password-reset, welcome-email, etc.

• email string optional

  Recipient email address. Can also be specified via setEmailField or use "NONE" to send only to BCC addresses.

• table string optional

  Database table name to link the notification to (e.g., aurora_orders, aurora_customers).

• master_id integer optional

  Record ID in the specified table to associate with this notification.

• data object optional

  Data object for template variable substitution. Field names in square brackets [fieldname] in the template will be replaced with corresponding values.

• SQL string optional

  Custom SQL query to fetch data for template merging. Alternative to providing the data object directly.

• setEmailField string optional

  Field name in the data object or SQL result containing the recipient's email address.

System Settings (Admin Controlled)

The notification system relies on several settings configured in the admin panel (stored in aurora_sites table):

• disable_email boolean

  When set to true, all email notifications for this application are disabled. API calls will return a "Notifications are disabled" error.

• email_from string

  Default sender email address used for all notifications unless overridden in the notification template.

• email_cc integer

  User ID of the account to CC on notifications. Email address is looked up from aurora_users table.

• email_bcc integer

  User ID of the account to BCC on notifications. Email address is looked up from aurora_users table.

Notification Templates

Notification templates are stored in the aurora_notifications table with the following key fields:

• event string

  Unique event identifier used to trigger this notification.

• enabled boolean

  Only enabled notifications can be triggered via the API.

• subject string

  Email subject line. Supports template variable substitution.

• content html

  HTML email body content. Field values from the data object in square brackets [fieldname] are replaced with actual values.

• from string optional

  Override sender email for this specific notification.

• bcc string optional

  Additional BCC recipients specific to this notification.

Notification Flow

1. API receives notification request with event name
2. System validates that notifications are enabled (disable_email = false)
3. Looks up notification template from aurora_notifications where event matches and enabled = 1
4. Merges data with notification template content (replaces [field] placeholders)
5. Creates log entry in aurora_notification_log with status 'Pending'
6. Links notification to record via aurora_related table (if table and master_id provided)
7. Background processor sends pending notifications and updates status to 'Sent'

Success Response (200 OK)

{
  "status": "Success"
}

Error Response - Notifications Disabled (200 OK)

{
  "status": "Failed",
  "message": "Notifications are disabled"
}

Error Response - Authentication Failed (401)

{
  "status": "Error",
  "message": "Unauthorized"
}

POST/message/sendPush

Sends push notifications to mobile devices using Web Push protocol.

Authentication

Required Header:

site-id: YOUR_APP_ID
or
x-site-id: YOUR_APP_ID

The application ID is automatically inherited from the header and cannot be forced through the request body.

Request Body

{
  "customerID": "encrypted_customer_id",
  "title": "New Order",
  "message": "You have a new order notification",
  "data": {
    "orderID": 5001,
    "type": "order_update"
  }
}

Parameters

• customerID string required

  Encrypted customer ID. The system will decrypt this to lookup push subscription details from aurora_customers table.

• title string optional

  Notification title. Defaults to "Notification" if not provided.

• message string required

  Notification body text.

• data object optional

  Additional data payload to include with the notification.

System Requirements

Push notifications require the following configuration:

• VAPID Keys

  Voluntary Application Server Identification (VAPID) keys must be configured in the application config. These keys are used to authenticate push notifications.

• Customer Subscription

  Customer must have previously subscribed to push notifications. Subscription details are stored in aurora_customers table with fields: pushsubscription, p256dh, and auth.

Success Response (200 OK)

{
  "status": "Success"
}

Error Response (200 OK)

{
  "status": "Error"
}

Security Considerations

Authentication & Authorization

Application ID Security

Prior to the security audit, the API accepted appID from the request body, which posed a security risk allowing clients to potentially send notifications on behalf of other applications. This vulnerability has been addressed:

Before (Insecure):

// ❌ VULNERABLE - appID could be forced from request body
POST /message/notification
Content-Type: application/json

{
  "appID": 999,  // Could be manipulated
  "event": "order-confirmation",
  ...
}

After (Secure):

// ✅ SECURE - appID inherited from authenticated header
POST /message/notification
site-id: YOUR_APP_ID
Content-Type: application/json

{
  "event": "order-confirmation",
  // No appID in body - inherited from header
  ...
}

Admin-Controlled Settings

Several security and operational controls are managed exclusively through the admin panel and cannot be overridden via the API:

• disable_email

  Admin Only: Administrators can disable all email notifications for an application. When disabled, API calls will fail with "Notifications are disabled" message. This provides an emergency stop for misbehaving applications.

• email_from

  Admin Only: Default sender address is controlled by administrators. This prevents API users from spoofing sender addresses.

• email_cc / email_bcc

  Admin Only: Copy recipients are controlled centrally to ensure compliance and audit trails.

• Notification Templates

  Admin Only: All notification templates are created and managed in the admin panel. API can only trigger existing, enabled templates - cannot create new ones or modify content.

Data Security

• SQL Injection Protection: All database queries use parameterized statements
• Encrypted IDs: Customer IDs and sensitive identifiers are encrypted when transmitted
• Template Validation: Only enabled notification templates can be triggered
• Scope Isolation: Applications can only access notifications within their appID scope

Best Practices

1. Always include site-id header: Never attempt to send appID in request body
2. Use event names: Reference pre-configured notification events rather than inline content
3. Sanitize user data: Clean any user-provided data before including in notification payloads
4. Monitor notification logs: Regularly review aurora_notification_log for unusual activity
5. Test with disable_email: Use the disable_email flag to safely test integrations
6. Limit notification frequency: Implement rate limiting in your application to prevent spam

Rate Limiting

The API includes built-in rate limiting to prevent abuse. Excessive notification requests may be throttled or blocked. Contact your administrator if you need higher limits for legitimate use cases.

Audit Trail

All notification attempts are logged in aurora_notification_log with the following information:

• Notification ID and event type
• Recipient email address
• Timestamp of creation and sending
• Status (Pending, Sent, Failed)
• Associated record (table and ID)

This audit trail enables compliance tracking and troubleshooting.