/api/qmail/net/messages/download

GET POST

Download an email from the RAIDA network using a file_guid from Client2 check/poll results.

http://localhost:8082/api/qmail/net/messages/download?file_guid={file_guid}

Description

The /api/qmail/net/messages/download endpoint triggers the download and local storage of an email identified by its file_guid. The handler accepts query parameters or form data. For one-click docs testing, use the GET-style link format shown on this page.

Stripe Recovery

The response includes both stripes_downloaded and stripes_recovered counts. Stripes are data fragments distributed across RAIDA servers. If some servers are unreachable, the system uses parity data to recover missing stripes automatically.

Direct Download Fallback

If no pending tell exists for the requested file_guid, the handler also accepts sender_sn so a developer can attempt a direct download during testing.

Parameters

Parameter	Type	Required	Description
`file_guid`	string	Yes	A 32-character hexadecimal GUID identifying the email to download. Obtained from a `/api/qmail/net/beacon/peek` or `/api/qmail/net/beacon/ping` notification.
`sender_sn`	integer	No	Optional fallback for direct download when the file GUID is no longer present in the pending tell table.

Parameter Format

This endpoint accepts standard application/x-www-form-urlencoded parameters or query string parameters.

Response

Returns a JSON object confirming the email was downloaded and stored locally, along with metadata about the downloaded email and stripe recovery statistics.

Success Response Properties (200 OK)

success boolean

Always true on success.

message string

Human-readable status message: "Email downloaded and stored".

email_id string

The hexadecimal identifier assigned to the locally stored email.

subject string

The subject line of the downloaded email.

sender_sn integer

The serial number of the sender.

stripes_downloaded integer

The number of data stripes successfully downloaded from RAIDA servers.

stripes_recovered integer

The number of data stripes recovered using parity data (when some servers were unreachable).

Example Success Response (200 OK)

{
  "success": true,
  "message": "Email downloaded and stored",
  "email_id": "f8e7d6c5b4a3f2e1d0c9b8a7f6e5d4c3",
  "subject": "Q4 Budget Report",
  "sender_sn": 1048576,
  "stripes_downloaded": 20,
  "stripes_recovered": 5
}

Error Responses

// 400 Bad Request - Missing parameter
{
  "error": true,
  "message": "Missing required parameter: file_guid",
  "code": 400
}

// 400 Bad Request - Invalid format
{
  "error": true,
  "message": "Invalid file_guid format (expected 32 hex chars)",
  "code": 400
}

// 404 Not Found - No pending tell
{
  "error": true,
  "message": "No pending tell found for this file_guid. Pass sender_sn to download directly.",
  "code": 404
}

// 500 Internal Server Error - Download failure
{
  "error": true,
  "message": "Download failed",
  "code": 500,
  "detail": "download_error"
}

Try It Out

Examples

cURL

# Download an email by file_guid
curl "http://localhost:8082/api/qmail/net/messages/download?file_guid=a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6"

# Expected response:
# {
#   "success": true,
#   "message": "Email downloaded and stored",
#   "email_id": "f8e7d6c5b4a3f2e1d0c9b8a7f6e5d4c3",
#   "subject": "Q4 Budget Report",
#   "sender_sn": 1048576,
#   "stripes_downloaded": 20,
#   "stripes_recovered": 5
# }

JavaScript (fetch)

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

async function downloadEmail(fileGuid) {
    try {
        const params = new URLSearchParams();
        params.append('file_guid', fileGuid);

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

        const result = await response.json();

        if (response.ok && result.success) {
            console.log('Email downloaded successfully!');
            console.log(`Email ID: ${result.email_id}`);
            console.log(`Subject: ${result.subject}`);
            console.log(`Sender SN: ${result.sender_sn}`);
            console.log(`Stripes downloaded: ${result.stripes_downloaded}`);
            console.log(`Stripes recovered: ${result.stripes_recovered}`);
        } else {
            console.error(`Download failed: ${result.message} (HTTP ${result.code ?? response.status})`);
            if (result.detail) {
                console.error(`Detail: ${result.detail}`);
            }
        }

        return result;
    } catch (error) {
        console.error('Error downloading email:', error);
    }
}

// Download email using file_guid from check/poll
downloadEmail('a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6');

Python

import requests

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

def download_email(file_guid):
    """Download an email from RAIDA by file_guid."""
    response = requests.post(
        f'{API_BASE}/qmail/net/messages/download',
        data={'file_guid': file_guid}
    )

    result = response.json()

    if response.ok and result.get('success'):
        print('Email downloaded successfully!')
        print(f"Email ID: {result['email_id']}")
        print(f"Subject: {result['subject']}")
        print(f"Sender SN: {result['sender_sn']}")
        print(f"Stripes downloaded: {result['stripes_downloaded']}")
        print(f"Stripes recovered: {result['stripes_recovered']}")
    else:
        print(f"Download failed: {result.get('message')} (HTTP {result.get('code', response.status_code)})")
        if result.get('detail'):
            print(f"Detail: {result['detail']}")

    return result

# Download email using file_guid from check/poll
download_email('a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6')

Related Endpoints

/api/qmail/db/messages/list

List downloaded emails in your inbox, sent, or trash folders after downloading.

View Details

/api/qmail/db/messages/get

Read full email details by email_id after a successful download.

View Details