/api/qmail/contacts/list

GET

Retrieve all contacts from your QMail address book.

http://localhost:8080/api/qmail/contacts/list

Description

The /api/qmail/contacts/list endpoint returns the complete list of contacts stored in your QMail address book. Each contact includes its CloudCoin serial number, denomination, name fields, auto-generated address, description, classification, favorite status, and creation timestamp. This endpoint takes no parameters.

No Parameters Required

This endpoint returns all contacts at once. No pagination, filtering, or query parameters are needed.

Parameters

This endpoint does not accept any parameters.

Response

Returns a JSON object containing the full list of contacts and a count.

Success Response Properties

success boolean
Always true on success.
count integer
Total number of contacts in the address book.
contacts array
Array of contact objects.

Contact Object Properties

serial_number integer
CloudCoin serial number for this contact.
denomination integer
Coin denomination.
first_name string
Contact's first name.
last_name string
Contact's last name.
auto_address string
Auto-generated address derived from name fields.
description string
Notes or description about the contact.
class_name string
Classification or group label.
is_favorite boolean
Whether the contact is marked as a favorite.
created_at integer (int64)
Unix timestamp of when the contact was created.

Example Success Response

{
  "success": true,
  "count": 2,
  "contacts": [
    {
      "serial_number": 1234567,
      "denomination": 1,
      "first_name": "Alice",
      "last_name": "Johnson",
      "auto_address": "alice.johnson",
      "description": "Team lead",
      "class_name": "work",
      "is_favorite": true,
      "created_at": 1700000000
    },
    {
      "serial_number": 7654321,
      "denomination": 5,
      "first_name": "Bob",
      "last_name": "Smith",
      "auto_address": "bob.smith",
      "description": "",
      "class_name": "friends",
      "is_favorite": false,
      "created_at": 1700100000
    }
  ]
}

Error Response Properties

success boolean
Always false on error.
message string
Human-readable error description.
error string
Machine-readable error code string.

Example Error Response (500 Internal Server Error)

{
  "success": false,
  "message": "Failed to list contacts",
  "error": "server_error"
}

Try It Out

This endpoint takes no parameters. Click the button below to retrieve all contacts.

Examples

cURL

# List all contacts
curl -X GET "http://localhost:8080/api/qmail/contacts/list"

JavaScript (fetch)

const API_BASE = 'http://localhost:8080/api';

async function listContacts() {
    try {
        const response = await fetch(`${API_BASE}/qmail/contacts/list`);
        const result = await response.json();

        if (result.success) {
            console.log(`Total contacts: ${result.count}`);

            result.contacts.forEach(contact => {
                console.log(`${contact.first_name} ${contact.last_name}`);
                console.log(`  Serial: ${contact.serial_number}`);
                console.log(`  Address: ${contact.auto_address}`);
                console.log(`  Favorite: ${contact.is_favorite}`);
                if (contact.description) {
                    console.log(`  Notes: ${contact.description}`);
                }
                console.log('');
            });
        } else {
            console.error('Failed to list contacts:', result.message);
        }
    } catch (error) {
        console.error('Error fetching contacts:', error);
    }
}

listContacts();

Python

import requests

API_BASE = 'http://localhost:8080/api'

def list_contacts():
    try:
        response = requests.get(f'{API_BASE}/qmail/contacts/list')
        result = response.json()

        if result.get('success'):
            print(f'Total contacts: {result["count"]}')

            for contact in result['contacts']:
                print(f'{contact["first_name"]} {contact["last_name"]}')
                print(f'  Serial: {contact["serial_number"]}')
                print(f'  Address: {contact["auto_address"]}')
                print(f'  Favorite: {contact["is_favorite"]}')
                if contact.get('description'):
                    print(f'  Notes: {contact["description"]}')
                print()
        else:
            print(f'Failed to list contacts: {result["message"]}')

    except Exception as e:
        print(f'Error fetching contacts: {str(e)}')

list_contacts()