/api/qmail/send

POST

Send an email through the QMail network with RAID-5 striped delivery.

POST /api/qmail/send

Description

The /api/qmail/send endpoint sends an email message through the QMail network. The message is striped across multiple RAIDA servers using RAID-5 redundancy, ensuring reliable delivery even if some servers are unavailable. Parameters are passed as standard form or query parameters (not a JSON body).

Parameter Format

This endpoint accepts standard application/x-www-form-urlencoded parameters or query string parameters. The to and body parameters are required. All other parameters are optional.

Parameters

Send parameters as form data or query string values:

Parameter Type Required Description
to string Yes Recipient address(es). Can be a QMail address or serial number.
body string Yes The email message body content.
cc string No CC (carbon copy) recipient address(es).
subject string No Email subject line.
storage_weeks integer No Number of weeks to store the message on the network. Default: 4.

Response

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

Success Response Properties

success boolean
Always true on success.
message string
Human-readable status message (e.g., "Email sent successfully").
file_guid string
A 32-character hexadecimal identifier for the sent message.
upload_successes integer
Number of RAIDA servers that successfully received the message.
upload_failures integer
Number of RAIDA servers that failed to receive the message.
tell_success boolean
Whether the recipient was successfully notified of the new message.

Example Success Response

{
  "success": true,
  "message": "Email sent successfully",
  "file_guid": "a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6",
  "upload_successes": 25,
  "upload_failures": 0,
  "tell_success": true
}

Error Response Properties

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

Example Error Response

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

Try It Out

Recipient address or serial number

Examples

cURL

curl -X POST "http://localhost:8080/api/qmail/send" \
  -d "to=12345678" \
  -d "body=Hello" \
  -d "subject=Test"

JavaScript (fetch)

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

async function sendEmail() {
    const params = new URLSearchParams({
        to: '12345678',
        body: 'Hello, this is a test message.',
        subject: 'Test Email',
        storage_weeks: '4'
    });

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

        const result = await response.json();

        if (result.success) {
            console.log('Email sent successfully!');
            console.log('File GUID:', result.file_guid);
            console.log('Upload successes:', result.upload_successes);
            console.log('Upload failures:', result.upload_failures);
            console.log('Tell success:', result.tell_success);
        } else {
            console.error('Failed to send email:', result.message);
            console.error('Error code:', result.error);
        }
    } catch (error) {
        console.error('Error sending email:', error);
    }
}

sendEmail();

Python

import requests

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

def send_email():
    params = {
        'to': '12345678',
        'body': 'Hello, this is a test message.',
        'subject': 'Test Email',
        'storage_weeks': 4
    }

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

        if result.get('success'):
            print('Email sent successfully!')
            print(f'File GUID: {result["file_guid"]}')
            print(f'Upload successes: {result["upload_successes"]}')
            print(f'Upload failures: {result["upload_failures"]}')
            print(f'Tell success: {result["tell_success"]}')
        else:
            print(f'Failed to send email: {result["message"]}')
            print(f'Error code: {result.get("error", "unknown")}')

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

send_email()