/api/qmail/ping

GET

Check for new mail via beacon signal. This endpoint queries the QMail beacon to determine if there are new messages waiting for retrieval without downloading the full message content.

http://localhost:8080/api/qmail/ping

Description

The /api/qmail/ping endpoint allows clients to efficiently check for new mail without downloading full message content. It queries the QMail beacon system, which provides a lightweight notification mechanism for incoming messages.

Efficient Mail Polling

This endpoint is designed for:

  • Checking for new messages without bandwidth overhead
  • Implementing real-time notification systems
  • Periodic polling for mail arrival
  • Getting message counts and basic metadata
Beacon System

The QMail beacon is a lightweight signaling system that indicates when new mail has arrived. The ping endpoint queries this beacon to provide instant notification of waiting messages without the overhead of retrieving full message content.

Interactive API Tester

Test this Endpoint

http://localhost:8080/api/qmail/ping

Parameters

This endpoint requires no parameters.

Response

Success Response Properties

status string
Request status indicator. Typically "ok" for successful queries.
timestamp integer
Unix timestamp (in seconds) when the beacon was checked.
beacon_status string
Status of the beacon system. Values include "active", "idle", or error states.
has_mail boolean
Indicates whether there are unread messages waiting (true) or not (false).
message_count integer
Number of unread messages waiting for retrieval.
messages array
Array of message metadata objects for waiting messages (IDs and basic info only).
messages[].id string
Unique identifier for the message.
messages[].timestamp integer
Unix timestamp when the message was received.
messages[].size integer
Size of the message in bytes.

Success Response Example (With Mail)

{
  "status": "ok",
  "timestamp": 1735689845,
  "beacon_status": "active",
  "has_mail": true,
  "message_count": 3,
  "messages": [
    {
      "id": "msg_a1b2c3d4e5",
      "timestamp": 1735689800,
      "size": 2048
    },
    {
      "id": "msg_f6g7h8i9j0",
      "timestamp": 1735689820,
      "size": 1536
    },
    {
      "id": "msg_k1l2m3n4o5",
      "timestamp": 1735689840,
      "size": 3072
    }
  ]
}

Success Response Example (No Mail)

{
  "status": "ok",
  "timestamp": 1735689845,
  "beacon_status": "idle",
  "has_mail": false,
  "message_count": 0,
  "messages": []
}

Examples

cURL

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

JavaScript (fetch)

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

if (result.has_mail) {
    console.log(`You have ${result.message_count} new message(s)!`);
    result.messages.forEach(msg => {
        console.log(`Message ID: ${msg.id}, Size: ${msg.size} bytes`);
    });
} else {
    console.log('No new mail.');
}

Use Cases

  • Mail Notifications: Check for new mail periodically without downloading full messages
  • Real-time Updates: Implement push notifications or live indicators for incoming mail
  • Bandwidth Optimization: Determine if there's mail before fetching full content
  • Message Preview: Get basic metadata (count, IDs, sizes) before retrieving full messages
  • Polling Optimization: Use as a lightweight check before calling more expensive retrieve operations

Important Notes

Lightweight Operation

This endpoint is designed to be called frequently. It only queries the beacon signal and returns metadata, not full message content. Use this for polling instead of repeatedly fetching all messages.

Message Metadata Only

The messages array contains only basic metadata (ID, timestamp, size). To retrieve the full message content, use the message retrieval endpoint with the message ID.

Polling Recommendations

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

  • Active use: Every 30-60 seconds
  • Background: Every 5-10 minutes
  • Consider implementing exponential backoff when no mail is present