/api/qmail/download

POST

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

POST /api/qmail/download

Description

The /api/qmail/download endpoint triggers the download and local storage of an email identified by its file_guid. The file_guid is a 32-character hexadecimal GUID obtained from a prior /api/qmail/check or /api/qmail/poll notification indicating that new mail is available on the RAIDA network.

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.

Parameters

Parameter Type Required Description
file_guid string Yes A 32-character hexadecimal GUID identifying the email to download. Obtained from a /api/qmail/check or /api/qmail/poll notification.
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
{
  "success": false,
  "message": "Missing required parameter: file_guid"
}

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

// 404 Not Found - No pending tell
{
  "success": false,
  "message": "No pending tell found for this file_guid"
}

// 500 Internal Server Error - Download failure
{
  "success": false,
  "message": "Download failed",
  "error": "download_error"
}

Try It Out

Enter a 32-character hexadecimal file_guid from a check/poll notification
http://localhost:8080/api/qmail/download
file_guid=

Examples

cURL

# Download an email by file_guid
curl -X POST "http://localhost:8080/api/qmail/download" \
  -d "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:8080/api';

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

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

        const result = await response.json();

        if (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);
        }

        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:8080/api'

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

    result = response.json()

    if 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')}")
        if 'error' in result:
            print(f"Error details: {result['error']}")

    return result

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

Related Endpoints

/api/qmail/inbox

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

View Details

/api/qmail/read

Read full email details by email_id after a successful download.

View Details