/api/qmail/local/inbox-fee

GET

Calculate the CloudCoin cost to send an email before uploading.

http://localhost:8080/api/qmail/local/inbox-fee?

Description

The /api/qmail/local/inbox-fee endpoint calculates the total CloudCoin cost to send an email without actually uploading anything. Use this to show the user how much an email will cost before they commit to sending it.

The fee is calculated based on the number of files (email body + attachments), the number of recipients (to + cc + bcc), and the storage duration. The returned value is in CloudCoins and may include fractional amounts (e.g., 343.003994).

Same Parameters as Upload

This endpoint accepts the same parameters as /api/qmail/net/messages/upload. The GUI can call seefees first to display the cost, then call upload with the same parameters if the user confirms.

Cost Calculation

Total cost = storage cost + inbox fees. Storage cost is 1 CC per server per file. Inbox fees are 10 CC per recipient. For example: 1 email + 2 attachments to 3 recipients = 15 CC storage + 30 CC inbox = 45 CC total.

Parameters

Send parameters as form data or query string values:

Parameter Type Required Description
sender integer No Qmail addressed used by the sender (Optional and for future use). By default, the api will uses your only one Qmail address.
to string Yes Simular to how PHP accepts array with multiple keys of the same name:
e.g. to=billy.jenkins@hotdog#8JD.Kilo&to=sara.Jones@viva#SE5.Mega
email_file string Yes Absolute path to the binary email file on the local filesystem (e.g., email_file=E:\Client_Data\outbox\msg001.qmail.
duration integer No Number of weeks to store the data on QMail servers. Range: 1–520. Default: Default is 8 months in Phase I.
cc string No Simular to how PHP accepts array with multiple keys of the same name:
e.g. cc=billy.jenkins@hotdog#8JD.Kilo&cc=sara.Jones@viva#SE5.Mega .
bcc string No Simular to how PHP accepts array with multiple keys of the same name:
e.g. bc=billy.jenkins@hotdog#8JD.Kilo&bc=sara.Jones@viva#SE5.Mega .
attachments string No List of absolute file paths for attachments (e.g., attachment=E:\files\doc.pdf&attachement=D:\docs\my.md"). Each attachment is uploaded independently using the same File GUID.
wallet_path string No Path to the wallet to use for payment. Defaults to the system default wallet. Otherwise wallet_path=C:\core\Client_Data\Wallets\Default\

Response

Returns a JSON object with the calculated fee breakdown.

Success Response Properties

status string
"success" when the fee calculation completes.
operation string
Always "seefees".
message string
Human-readable summary of the fee estimate.
total_cost_cc number
Total cost in CloudCoin (storage + inbox fees). May be a whole number, fraction, or both (e.g., 343.003994).
storage_cost_cc number
Storage cost component in CloudCoin.
inbox_cost_cc number
Inbox fee component in CloudCoin.
total_recipients integer
Total number of recipients (to + cc + bcc).
total_files integer
Total number of files (1 email + number of attachments).
duration_weeks integer
Storage duration used for the calculation (in weeks).

Example Success Response

{
  "status": "success",
  "operation": "seefees",
  "message": "Estimated cost: 343.003994 CC for 3 files to 3 recipients over 4 weeks",
  "total_cost_cc": 343.003994,
  "storage_cost_cc": 313.003994,
  "inbox_cost_cc": 30,
  "total_recipients": 3,
  "total_files": 3,
  "duration_weeks": 4
}

Error Response Properties

status string
"fail" when the fee calculation fails.
operation string
Always "seefees".
error_code integer
Machine-readable error code identifying the failure type.
message string
Human-readable error description.

Example Error Responses

// Missing required parameter
{
  "status": "fail",
  "operation": "seefees",
  "error_code": 400,
  "message": "Missing required parameter: to"
}

// Email file not found
{
  "status": "fail",
  "operation": "seefees",
  "error_code": 404,
  "message": "Email file not found: E:\\outbox\\msg001.qmail"
}

// Invalid recipient address
{
  "status": "fail",
  "operation": "seefees",
  "error_code": 422,
  "message": "Invalid QMail address: billy.jenkins@hotdog. Missing domain separator '#'."
}

Try It Out

Serial number of your identity coin
Human-readable value (e.g., 1, 0.01)
Comma-separated QMail addresses (Name#SerialNumber)
Absolute path to the binary .qmail email file
Comma-separated absolute file paths

Examples

cURL

# Check fees for a simple email (no attachments)
curl "http://localhost:8080/api/qmail/local/inbox-fee?\
sender_id=16777216&\
sender_denomination=1&\
to=Sean%2316777216&\
email_file=E%3A%5CClient_Data%5Coutbox%5Cmessage.qmail&\
duration=4"

# Check fees for email with attachments and CC
curl "http://localhost:8080/api/qmail/local/inbox-fee?\
sender_id=16777216&\
sender_denomination=1&\
to=Sean%2316777216,Bob%239876543&\
cc=Alice%235555555&\
email_file=E%3A%5CClient_Data%5Coutbox%5Cmessage.qmail&\
attachments=E%3A%5Cfiles%5Cphoto.jpg,E%3A%5Cfiles%5Cdoc.pdf&\
duration=8"

JavaScript (fetch)

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

async function checkFees() {
    const params = new URLSearchParams({
        sender_id: '16777216',
        sender_denomination: '1',
        to: 'Sean#16777216,Bob#9876543',
        email_file: 'E:\\Client_Data\\outbox\\message.qmail',
        attachments: 'E:\\files\\photo.jpg,E:\\files\\doc.pdf',
        cc: 'Alice#5555555',
        duration: '4'
    });

    try {
        const response = await fetch(`${API_BASE}/qmail/local/inbox-fee?${params}`);
        const result = await response.json();

        if (result.status === 'success') {
            console.log('Fee estimate:');
            console.log('  Total cost:', result.total_cost_cc, 'CC');
            console.log('  Storage:', result.storage_cost_cc, 'CC');
            console.log('  Inbox fees:', result.inbox_cost_cc, 'CC');
            console.log('  Recipients:', result.total_recipients);
            console.log('  Files:', result.total_files);
            console.log('  Duration:', result.duration_weeks, 'weeks');

            // Ask user to confirm before uploading
            if (confirm(`Send email for ${result.total_cost_cc} CC?`)) {
                await fetch(`${API_BASE}/qmail/net/messages/upload`, {
                    method: 'POST',
                    headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
                    body: params.toString()
                });
            }
        } else {
            console.error('Fee check failed:', result.message);
        }
    } catch (error) {
        console.error('Error:', error);
    }
}

checkFees();

Python

import requests

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

def check_fees():
    params = {
        'sender_id': '16777216',
        'sender_denomination': '1',
        'to': 'Sean#16777216,Bob#9876543',
        'email_file': r'E:\Client_Data\outbox\message.qmail',
        'attachments': r'E:\files\photo.jpg,E:\files\doc.pdf',
        'cc': 'Alice#5555555',
        'duration': 4
    }

    try:
        response = requests.get(f'{API_BASE}/qmail/local/inbox-fee', params=params)
        result = response.json()

        if result.get('status') == 'success':
            print('Fee estimate:')
            print(f'  Total cost: {result["total_cost_cc"]} CC')
            print(f'  Storage: {result["storage_cost_cc"]} CC')
            print(f'  Inbox fees: {result["inbox_cost_cc"]} CC')
            print(f'  Recipients: {result["total_recipients"]}')
            print(f'  Files: {result["total_files"]}')
            print(f'  Duration: {result["duration_weeks"]} weeks')

            confirm = input(f'Send email for {result["total_cost_cc"]} CC? (y/n): ')
            if confirm.lower() == 'y':
                upload = requests.post(f'{API_BASE}/qmail/net/messages/upload', data=params)
                print(upload.json())
        else:
            print(f'Fee check failed: {result["message"]}')

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

check_fees()