System API Documentation

System health monitoring and diagnostics endpoints for infrastructure components.

Check System Health

GET /api/v1/system-health-check

API Usage Notes

• Authentication required: Admin API Key (via Bearer token or query parameter)
• Legacy endpoint access via /api.php is also supported

Request Parameters:

Parameter	Type	Required	Description
Command	String	Yes	API command: system.health.check (only for legacy endpoint)
AdminAPIKey	String	No	Admin API key for authentication (alternative to Bearer token)

Authentication Methods:

This endpoint supports two authentication methods:

1. Bearer Token (Recommended): Include the Admin API Key in the Authorization header:

   Authorization: Bearer YOUR_ADMIN_API_KEY

2. Query Parameter: Pass the Admin API Key as a query parameter:

   ?adminapikey=YOUR_ADMIN_API_KEY

Example Request (Bearer Token)

curl -X GET https://example.com/api/v1/system-health-check \
  -H "Authorization: Bearer YOUR_ADMIN_API_KEY"

Example Request (Query Parameter)

curl -X GET "https://example.com/api/v1/system-health-check?adminapikey=YOUR_ADMIN_API_KEY"

Example Request (Legacy)

curl -X GET "https://example.com/api.php?Command=system.health.check&adminapikey=YOUR_ADMIN_API_KEY"

Success Response (HTTP 200)

{
  "Checks": {
    "MySQL": "OK",
    "ClickHouse": "OK",
    "Elasticsearch": "OK",
    "RabbitMQ": "OK",
    "Redis": "OK",
    "Session": "OK",
    "SystemContainer": "OK",
    "Vector": "OK",
    "Haproxy": "OK",
    "Cron": "OK",
    "Supervisor": "OK",
    "SendEngine": "OK",
    "AdminFrontend": "OK",
    "UserFrontend": "OK",
    "FilePermissions": "OK"
  }
}

Partial Failure Response (HTTP 503)

{
  "Checks": {
    "MySQL": "OK",
    "ClickHouse": "OK",
    "Elasticsearch": "Connection refused",
    "RabbitMQ": "OK",
    "Redis": "[111] Connection refused",
    "Session": "OK",
    "SystemContainer": "OK",
    "Vector": "Timeout after 3 seconds",
    "Haproxy": "OK",
    "Cron": "App container cron not executing (last run: 120 seconds ago)",
    "Supervisor": "# campaign_delivery_worker: STOPPED # journey_worker: FATAL ",
    "SendEngine": "No send engine containers running",
    "AdminFrontend": "OK",
    "UserFrontend": "Backend user login form action is not found",
    "FilePermissions": "logs/campaign_delivery.log: expected 0777, 0666 or 0644, found 0640"
  }
}

Authentication Error (HTTP 403)

{
  "Errors": [
    {
      "Code": 1,
      "Message": "Authentication failed. Invalid admin API key."
    }
  ]
}

Error Codes

0: Success - All health checks passed
1: Authentication failed. Invalid admin API key.

HTTP Status Codes:
200: All health checks passed
403: Authentication failed
503: One or more health checks failed (see Checks object for details)

Health Check Components:

The endpoint performs comprehensive health checks on the following components:

• MySQL: Database connectivity and admin user existence
• ClickHouse: Analytics database connectivity
• Elasticsearch: Search engine connectivity and indices
• RabbitMQ: Message queue connectivity
• Redis: Cache server connectivity
• Session: PHP session functionality
• SystemContainer: Laravel backend container health (/system/ping)
• Vector: Log aggregation service health
• Haproxy: Load balancer connectivity
• Cron: App and system container cron job execution (heartbeat checks)
• Supervisor: Process manager status for all managed processes
• SendEngine: Send engine container discovery and supervisor process status
• AdminFrontend: Admin login page accessibility and form validation
• UserFrontend: User login page accessibility and form validation
• FilePermissions: Directory and log file permissions (expects 0777 for directories, 0777/0666/0644 for log files)

Response Details:

• Each check returns "OK" if successful
• Failed checks return detailed error messages explaining the failure
• HTTP status code 200 indicates all checks passed
• HTTP status code 503 indicates one or more checks failed (response still includes all check results)
• The Cron check monitors heartbeat files updated every minute; considers cron failed if > 90 seconds since last update
• The Supervisor check reports processes not in RUNNING state with format: # process_name: STATE
• The SendEngine check discovers containers dynamically using Docker Compose project prefix detection

Process PowerMTA Log File

POST /api/v1/process_pmta_log_file

API Usage Notes

• Authentication required: Admin API Key (via Bearer token)
• Rate limit: 100 requests per 60 seconds
• This endpoint is designed for PowerMTA integration to process email delivery logs
• Accepts batch processing of email events (delivery, bounce, etc.)
• Legacy endpoint access via /api.php is also supported

Request Body Parameters:

Parameter	Type	Required	Description
AdminAPIKey	String	Yes	Admin API key for authentication (via Bearer token)
LogData	Array	Yes	Array of PowerMTA log entries (JSON format in POST body)

PowerMTA Log Entry Format:

Each log entry in the array should contain PowerMTA event data following the PowerMTA log format specification.

Example Request

curl -X POST https://example.com/api/v1/process_pmta_log_file \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_ADMIN_API_KEY" \
  -d '[
    {
      "type": "delivery",
      "timeLogged": "2025-01-15T10:30:00Z",
      "recipient": "user@example.com",
      "messageId": "550e8400-e29b-41d4-a716-446655440000"
    },
    {
      "type": "bounce",
      "timeLogged": "2025-01-15T10:31:00Z",
      "recipient": "invalid@example.com",
      "bounceType": "hard"
    }
  ]'

Success Response

{
  "Success": true,
  "ProcessedCount": 2,
  "ErrorCount": 0
}

Error Response - Auth

{
  "Errors": [
    {
      "Code": 1,
      "Message": "Invalid AdminAPIKey"
    }
  ]
}

Error Response - Invalid Data

{
  "Errors": [
    {
      "Code": 2,
      "Message": "Invalid or empty log data"
    }
  ]
}

HTTP Status Codes

200: Success - Log data processed successfully
400: Bad Request - Invalid or empty log data
401: Unauthorized - Invalid Admin API Key
429: Too many requests - Rate limit exceeded

Error Codes

1: Invalid AdminAPIKey
2: Invalid or empty log data

Processing Behavior:

• Accepts both JSON and form-encoded POST data
• Processes events in batch for improved performance
• Returns processing results with success/error counts
• Failed events within a batch do not cause the entire batch to fail

Get System Settings

GET /api/v1/system-settings

API Usage Notes

• Authentication required: Admin API Key (or logged-in admin session)
• Legacy endpoint access via /api.php is also supported

Returns a unified snapshot of every Octeth configuration value the running instance can see. Settings are grouped by source so callers can drill into a specific layer without merging four separate views themselves.

The endpoint surfaces four sources:

1. ConfigFiles — every *.php file under config/global/ (each returns an array). The app.php file is intentionally skipped because it declares the SystemConfig class and has side effects; its values are already represented in EnvSettings.octeth and DefinedConstants.
2. EnvSettings — SystemConfig::$Config, populated from the six .oempro_*_env files: octeth, mysql, redis, rabbitmq, clickhouse, supervisor.
3. RuntimeOptions — every row in the oempro_options table (the runtime-editable options used by OemproOptions::get()/set()). JSON-encoded values are decoded automatically when they are arrays.
4. DefinedConstants — get_defined_constants(true)['user']: every constant registered by ConfigLoader plus library define() calls.

Sensitive value redaction: any key whose name contains a known secret substring (case-insensitive: PASSWORD, PASSWD, _PASS, SECRET, SALT, TOKEN, API_KEY, APIKEY, CLIENT_SECRET, ENCRYPTION_KEY, HMAC, ERLANG_COOKIE, LICENSE_KEY, AUTH_CODE, BUGSNAG_API, SENTRY_API, PRIVATE_KEY, WEBHOOK_SECRET) has its value replaced with the literal string "***REDACTED***". The key itself remains visible. Empty values pass through untouched so callers can distinguish "configured but blank" from "configured with a value, redacted".

Request Parameters:

Parameter	Type	Required	Description
Command	String	Yes	API command: system.getsettings (only for legacy endpoint)
AdminAPIKey	String	No	Admin API key for authentication (alternative to logged-in admin session). Sent as adminapikey query parameter.
Section	String	No	Restrict the response to a single source. Possible values: ConfigFiles, EnvSettings, RuntimeOptions, DefinedConstants. If omitted, all four sections are returned.

Example Request

curl -X GET "https://example.com/api/v1/system-settings?adminapikey=YOUR_ADMIN_API_KEY"

Example Request (Legacy)

curl -X GET "https://example.com/api.php?Command=System.GetSettings&adminapikey=YOUR_ADMIN_API_KEY"

Example Request (Filtered)

curl -X GET "https://example.com/api/v1/system-settings?Section=EnvSettings&adminapikey=YOUR_ADMIN_API_KEY"

Success Response

{
  "Success": true,
  "Settings": {
    "ConfigFiles": {
      "email_delivery": { "EMAIL_DELIVERY_BATCH_SIZE": 100 },
      "sms": { "SMS_GATEWAY_TIMEOUT": 30 }
    },
    "EnvSettings": {
      "octeth": {
        "APP_URL": "https://example.com/",
        "PRODUCT_VERSION": "5.9.1",
        "MYSQL_PASSWORD": "***REDACTED***",
        "LICENSE_KEY": "***REDACTED***",
        "OEMPRO_PASSWORD_SALT": "***REDACTED***"
      },
      "mysql":      { "MYSQL_HOST": "oempro_mysql", "MYSQL_PASSWORD": "***REDACTED***" },
      "redis":      { "REDIS_HOST": "oempro_redis" },
      "rabbitmq":   { "RABBITMQ_DEFAULT_USER": "oempro", "RABBITMQ_DEFAULT_PASS": "***REDACTED***" },
      "clickhouse": { "CLICKHOUSE_HOST": "oempro_clickhouse" },
      "supervisor": { "SUPERVISOR_USERNAME": "admin" }
    },
    "RuntimeOptions": {
      "FailedWebhookHandler": "email",
      "DisableUserPasswordReset": ""
    },
    "DefinedConstants": {
      "APP_PATH": "/var/www/html",
      "CHARSET": "utf-8",
      "OEMPRO_DEBUG": true,
      "PRODUCT_VERSION": "5.9.1",
      "ADMIN_API_KEY": "***REDACTED***"
    }
  }
}

Error Response

{
  "Success": false,
  "ErrorCode": 1,
  "ErrorMessage": "Invalid Section. Allowed: ConfigFiles, EnvSettings, RuntimeOptions, DefinedConstants"
}

Error Codes

1: Invalid Section value (must be one of ConfigFiles, EnvSettings, RuntimeOptions, DefinedConstants)
99998: Authentication required - missing or invalid admin credentials

Use cases:

• Diagnosing configuration drift between environments
• Support escalations where the operator needs to share a redacted config snapshot
• Verifying that a setting (env var, runtime option, or constant) is actually present and reaching the application
• Auditing which secrets are configured without exposing their values