/api/qmail/counts
GETGet per-folder email counts including total and unread messages.
GET /api/qmail/counts
Description
The GET /api/qmail/counts endpoint returns email counts for each folder, including the total number of emails and the number of unread emails. This is useful for displaying badge counts or folder summaries in the user interface.
Real-time Counts
Counts are queried directly from the database and reflect the current state. Trashed emails are excluded from inbox counts and only appear in the trash folder count.
Parameters
This endpoint requires no parameters.
Response
Returns a JSON object with per-folder count objects.
Response Properties
success
boolean
Indicates whether the operation completed successfully.
folders
object
Object with folder names as keys, each containing count data.
{folder_name}
object
Count data for each folder (inbox, sent, drafts, trash, starred, archive).
total
integer
Total number of emails in this folder.
unread
integer
Number of unread emails in this folder.
Example Success Response
{
"success": true,
"folders": {
"inbox": {"total": 42, "unread": 5},
"sent": {"total": 18, "unread": 0},
"drafts": {"total": 3, "unread": 0},
"trash": {"total": 7, "unread": 0},
"starred": {"total": 12, "unread": 2},
"archive": {"total": 156, "unread": 0}
}
}Example Error Response (500 Internal Error)
{
"success": false,
"message": "Failed to query folder counts"
}Try It Out
Examples
cURL
curl "http://localhost:8080/api/qmail/counts"JavaScript (async/await)
const API_HOST = 'http://localhost:8080';
async function getFolderCounts() {
try {
const response = await fetch(`${API_HOST}/api/qmail/counts`);
const result = await response.json();
if (result.success) {
for (const [name, counts] of Object.entries(result.folders)) {
const badge = counts.unread > 0 ? ` (${counts.unread} unread)` : '';
console.log(`${name}: ${counts.total} emails${badge}`);
}
}
return result;
} catch (error) {
console.error('Error getting counts:', error);
}
}
getFolderCounts();Python
import requests
API_HOST = 'http://localhost:8080'
def get_folder_counts():
response = requests.get(f'{API_HOST}/api/qmail/counts')
result = response.json()
if result.get('success'):
for name, counts in result['folders'].items():
badge = f" ({counts['unread']} unread)" if counts['unread'] > 0 else ''
print(f"{name}: {counts['total']} emails{badge}")
return result
get_folder_counts()