/api/qmail/check

GET

Quick non-blocking peek for new mail. Queries the beacon system to determine if there are new messages waiting for retrieval and returns immediately.

http://localhost:8080/api/qmail/check

Description

The /api/qmail/check endpoint provides a quick, non-blocking way to check for new mail. It performs a single peek on the QMail beacon system, returning immediately with any available notifications.

Quick Peek

This endpoint is designed for:

  • Fast new-mail checks without long waits
  • Periodic polling with minimal latency
  • UI badge/counter updates for incoming messages
  • Getting notification metadata (sender, file size, type) without downloading content
Check vs. Poll

Unlike the /api/qmail/poll endpoint which blocks for up to 10 minutes waiting for new mail, this endpoint returns immediately. Use /check for fast UI updates and /poll for efficient long-polling notification systems.

Parameters

This endpoint requires no parameters. It uses the internal beacon state automatically.

Response

Success Response Properties

success boolean
Indicates whether the check completed successfully. true on success.
new_mail_count integer
The number of new mail notifications returned in this response.
total_remaining integer
The total number of notifications still remaining in the beacon queue after this response.
notifications array
Array of notification objects describing each new mail item.

Notification Object Properties

file_guid string
Hexadecimal GUID identifying the incoming file.
sender_sn integer
The serial number of the sender.
timestamp integer
Unix timestamp (in seconds) when the notification was created.
tell_type integer
Numeric type code indicating the kind of notification (e.g., message, file transfer).
total_file_size integer
Total size of the incoming file in bytes.

Success Response Example (New Mail Found)

{
  "success": true,
  "new_mail_count": 2,
  "total_remaining": 5,
  "notifications": [
    {
      "file_guid": "a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6",
      "sender_sn": 14582,
      "timestamp": 1735689800,
      "tell_type": 1,
      "total_file_size": 2048
    },
    {
      "file_guid": "f6e5d4c3b2a1f6e5d4c3b2a1f6e5d4c3",
      "sender_sn": 28743,
      "timestamp": 1735689820,
      "tell_type": 1,
      "total_file_size": 15360
    }
  ]
}

Success Response Example (No New Mail)

{
  "success": true,
  "new_mail_count": 0,
  "total_remaining": 0,
  "notifications": []
}

Error Response Example

{
  "success": false,
  "message": "Beacon check failed",
  "error": "beacon_unavailable"
}

Interactive API Tester

Test this Endpoint

http://localhost:8080/api/qmail/check

Examples

cURL

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

JavaScript (fetch)

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

if (result.success && result.new_mail_count > 0) {
    console.log(`You have ${result.new_mail_count} new message(s)!`);
    console.log(`${result.total_remaining} more waiting in queue.`);
    result.notifications.forEach(n => {
        console.log(`File: ${n.file_guid}, Sender SN: ${n.sender_sn}, Size: ${n.total_file_size} bytes`);
    });
} else if (result.success) {
    console.log('No new mail.');
} else {
    console.error('Check failed:', result.message);
}

Python

import requests

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

if result['success'] and result['new_mail_count'] > 0:
    print(f"You have {result['new_mail_count']} new message(s)!")
    print(f"{result['total_remaining']} more waiting in queue.")
    for n in result['notifications']:
        print(f"  File: {n['file_guid']}, Sender SN: {n['sender_sn']}, Size: {n['total_file_size']} bytes")
elif result['success']:
    print('No new mail.')
else:
    print(f"Check failed: {result['message']}")

Important Notes

Non-Blocking

This endpoint returns immediately with the current beacon state. If no new mail is available, the response returns with new_mail_count: 0. For blocking long-poll behavior, use the /api/qmail/poll endpoint instead.

Notification Metadata Only

The notifications array contains only lightweight metadata (GUID, sender serial number, timestamp, type, and file size). To retrieve the full message content, use the appropriate retrieval endpoint with the file_guid.

Polling Recommendations

While this endpoint is lightweight and fast, avoid excessive polling. Recommended intervals:

  • Active use: Every 15-30 seconds
  • Background: Every 2-5 minutes
  • For real-time notifications, prefer the long-poll /api/qmail/poll endpoint