/api/qmail/status

GET

Service status endpoint that returns beacon state, database statistics, and QMail server information. Use this endpoint to monitor the overall health and configuration of the QMail system.

http://localhost:8080/api/qmail/status

Description

The /api/qmail/status endpoint provides a comprehensive view of the QMail system's current state. It returns information about the beacon process, local database statistics, and the list of configured RAIDA servers.

System Monitoring

This endpoint is ideal for:

  • Monitoring beacon health and error state
  • Tracking mailbox statistics (inbox, sent, trash, unread counts)
  • Verifying RAIDA server configuration and connectivity
  • Dashboards and administrative status panels

Interactive API Tester

Test this Endpoint

http://localhost:8080/api/qmail/status

Parameters

This endpoint requires no parameters.

Response

Success Response Properties

success boolean
Indicates whether the status request completed successfully.

beacon Object

beacon.running boolean
Whether the beacon process is currently running and actively checking for new mail.
beacon.last_tell_timestamp integer
Unix timestamp of the last successful beacon tell operation. A value of 0 indicates the beacon has not yet completed a tell cycle.
beacon.backoff_seconds integer
Current backoff delay in seconds before the next beacon poll. Increases when consecutive errors occur.
beacon.consecutive_errors integer
Number of consecutive errors encountered by the beacon. Resets to 0 on a successful poll.

database Object

database.open boolean
Whether the local SQLite database is open and accessible.
database.inbox_count integer
Total number of emails in the inbox folder.
database.sent_count integer
Total number of emails in the sent folder.
database.trash_count integer
Total number of emails in the trash folder.
database.unread_count integer
Total number of unread emails across all folders.
database.contact_count integer
Total number of contacts stored in the address book.

servers Object

servers.count integer
Total number of RAIDA servers configured.
servers.data_stripes integer
Number of data stripes used for redundant mail storage across RAIDA servers.
servers.list array
Array of server objects describing each configured RAIDA server.
servers.list[].raida_index integer
Index number of the RAIDA server (0-24).
servers.list[].ip string
IP address of the RAIDA server.
servers.list[].port integer
Port number the RAIDA server listens on.
servers.list[].region string
Geographic region where the RAIDA server is located (e.g., "us-east", "eu-west").
servers.list[].hostname string
Hostname of the RAIDA server.

Success Response Example

{
  "success": true,
  "beacon": {
    "running": true,
    "last_tell_timestamp": 1735689800,
    "backoff_seconds": 0,
    "consecutive_errors": 0
  },
  "database": {
    "open": true,
    "inbox_count": 42,
    "sent_count": 18,
    "trash_count": 5,
    "unread_count": 7,
    "contact_count": 23
  },
  "servers": {
    "count": 25,
    "data_stripes": 5,
    "list": [
      {
        "raida_index": 0,
        "ip": "1.2.3.4",
        "port": 18000,
        "region": "us-east",
        "hostname": "raida0.cloudcoin.global"
      },
      {
        "raida_index": 1,
        "ip": "5.6.7.8",
        "port": 18000,
        "region": "eu-west",
        "hostname": "raida1.cloudcoin.global"
      }
    ]
  }
}

Examples

cURL

curl "http://localhost:8080/api/qmail/status"

JavaScript (fetch)

const response = await fetch('http://localhost:8080/api/qmail/status');
const result = await response.json();

if (result.success) {
    console.log('Beacon running:', result.beacon.running);
    console.log('Unread emails:', result.database.unread_count);
    console.log('Inbox count:', result.database.inbox_count);
    console.log('RAIDA servers:', result.servers.count);

    if (result.beacon.consecutive_errors > 0) {
        console.warn('Beacon errors:', result.beacon.consecutive_errors);
    }
}

Python

import requests

response = requests.get('http://localhost:8080/api/qmail/status')
data = response.json()

if data['success']:
    beacon = data['beacon']
    db = data['database']
    servers = data['servers']

    print(f"Beacon running: {beacon['running']}")
    print(f"Consecutive errors: {beacon['consecutive_errors']}")
    print(f"Database open: {db['open']}")
    print(f"Inbox: {db['inbox_count']}, Unread: {db['unread_count']}")
    print(f"Sent: {db['sent_count']}, Trash: {db['trash_count']}")
    print(f"Contacts: {db['contact_count']}")
    print(f"RAIDA servers: {servers['count']} ({servers['data_stripes']} stripes)")

    for server in servers['list']:
        print(f"  [{server['raida_index']}] {server['hostname']} - {server['region']}")

Use Cases

  • System Dashboard: Display real-time beacon health, mailbox counts, and server topology in an admin panel
  • Health Monitoring: Track beacon errors and backoff state to detect connectivity issues early
  • Mailbox Overview: Show inbox, sent, trash, and unread counts without fetching individual messages
  • Server Inventory: Enumerate configured RAIDA servers and verify regional distribution
  • Startup Validation: Confirm the database is open and beacon is running before making other API calls

Important Notes

Public Endpoint

This is a public endpoint that requires no authentication. It is designed to be lightweight and respond quickly for monitoring purposes.

Beacon Backoff

When the beacon encounters errors, it uses an exponential backoff strategy. The backoff_seconds field shows the current delay, and consecutive_errors indicates how many failures have occurred in a row. Both reset to 0 on a successful poll cycle.

Server List Truncation

The servers.list array contains all configured RAIDA servers (typically 25). When displaying server information, consider paginating or summarizing the list for user interfaces.