/api/qmail/contacts/add

POST

Add a new contact to your QMail address book by CloudCoin serial number.

POST /api/qmail/contacts/add

Description

The /api/qmail/contacts/add endpoint creates a new contact entry in your address book. Each contact is identified by a CloudCoin serial number and can include optional name fields, a description, and a classification. The server automatically generates an auto_address from the provided name fields.

Parameter Format

This endpoint accepts standard application/x-www-form-urlencoded parameters or query string parameters. The serial_number parameter is required. All other parameters are optional.

Auto-Generated Address

The auto_address field is automatically generated by the server from the first_name and last_name fields. You do not need to provide it.

Parameters

Send parameters as form data or query string values:

Parameter Type Required Description
serial_number string/int Yes CloudCoin serial number for the contact (1 - 16,777,216).
denomination integer No Coin denomination. Default: 1.
first_name string No Contact's first name. Used to generate the auto_address.
last_name string No Contact's last name. Used to generate the auto_address.
description string No Notes or description about the contact.
class_name string No Classification or group label for the contact.

Response

Returns a JSON object indicating the result of the add operation.

Success Response Properties

success boolean
Always true on success.
message string
"Contact added".
serial_number integer
The serial number of the newly added contact.
auto_address string
Auto-generated address derived from the name fields.

Example Success Response

{
  "success": true,
  "message": "Contact added",
  "serial_number": 1234567,
  "auto_address": "alice.johnson"
}

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 (400 Bad Request)

{
  "success": false,
  "message": "Missing required parameter: serial_number",
  "error": "invalid_request"
}

Example Error Response (500 Internal Server Error)

{
  "success": false,
  "message": "Failed to add contact",
  "error": "server_error"
}

Try It Out

CloudCoin serial number (1 - 16,777,216)

Examples

cURL

# Add a contact with all fields
curl -X POST "http://localhost:8080/api/qmail/contacts/add" \
  -d "serial_number=1234567" \
  -d "denomination=1" \
  -d "first_name=Alice" \
  -d "last_name=Johnson" \
  -d "description=Team lead" \
  -d "class_name=work"

# Minimal - only serial number
curl -X POST "http://localhost:8080/api/qmail/contacts/add" \
  -d "serial_number=1234567"

JavaScript (fetch)

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

async function addContact() {
    const params = new URLSearchParams({
        serial_number: '1234567',
        denomination: '1',
        first_name: 'Alice',
        last_name: 'Johnson',
        description: 'Team lead',
        class_name: 'work'
    });

    try {
        const response = await fetch(`${API_BASE}/qmail/contacts/add`, {
            method: 'POST',
            headers: {
                'Content-Type': 'application/x-www-form-urlencoded'
            },
            body: params.toString()
        });

        const result = await response.json();

        if (result.success) {
            console.log('Contact added successfully!');
            console.log('Serial Number:', result.serial_number);
            console.log('Auto Address:', result.auto_address);
        } else {
            console.error('Failed to add contact:', result.message);
        }
    } catch (error) {
        console.error('Error adding contact:', error);
    }
}

addContact();

Python

import requests

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

def add_contact():
    params = {
        'serial_number': '1234567',
        'denomination': 1,
        'first_name': 'Alice',
        'last_name': 'Johnson',
        'description': 'Team lead',
        'class_name': 'work'
    }

    try:
        response = requests.post(f'{API_BASE}/qmail/contacts/add', data=params)
        result = response.json()

        if result.get('success'):
            print('Contact added successfully!')
            print(f'Serial Number: {result["serial_number"]}')
            print(f'Auto Address: {result["auto_address"]}')
        else:
            print(f'Failed to add contact: {result["message"]}')

    except Exception as e:
        print(f'Error adding contact: {str(e)}')

add_contact()