/api/qmail/net/beacon/peek

GET

Quick non-blocking peek for new mail on Client2. This one-click link uses since=0 so developers can see the full current tell queue during testing.

http://localhost:8082/api/qmail/net/beacon/peek?since=0

Description

The /api/qmail/net/beacon/peek endpoint provides a quick, non-blocking way to check for new mail. It also returns a debug object containing the current beacon RAIDA, mailbox serial number, denomination, and a short AN preview.

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/net/beacon/ping 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 uses the internal beacon state automatically. For testing, you can optionally pass since as a Unix timestamp; since=0 asks for all available tells.

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.
debug object
Diagnostic beacon context returned on every response.

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)

{
  "debug": {
    "beacon_raida": 11,
    "serial_number": 5735,
    "denomination": 1,
    "since_timestamp": 0,
    "an_preview": "a1b2c3d4..."
  },
  "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)

{
  "debug": {
    "beacon_raida": 11,
    "serial_number": 5735,
    "denomination": 1,
    "since_timestamp": 0,
    "an_preview": "a1b2c3d4..."
  },
  "success": true,
  "new_mail_count": 0,
  "total_remaining": 0,
  "notifications": []
}

Error Response Example

{
  "error": true,
  "message": "Peek failed",
  "code": 500,
  "detail": "network_error",
  "debug": {
    "beacon_raida": 11,
    "serial_number": 5735,
    "denomination": 1,
    "since_timestamp": 0,
    "an_preview": "a1b2c3d4..."
  }
}

Interactive API Tester

Test this Endpoint

http://localhost:8082/api/qmail/net/beacon/peek?since=0

Examples

cURL

curl "http://localhost:8082/api/qmail/net/beacon/peek?since=0"

JavaScript (fetch)

const response = await fetch('http://localhost:8082/api/qmail/net/beacon/peek?since=0');
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:8082/api/qmail/net/beacon/peek?since=0')
result = response.json()

if response.ok and result.get('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 response.ok and result.get('success'):
    print('No new mail.')
else:
    print(f"Check failed: {result['message']} (HTTP {result.get('code', response.status_code)})")
    if result.get('detail'):
        print(f"Detail: {result['detail']}")

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/net/beacon/ping 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/net/beacon/ping endpoint