/api/mail/send

POST

Send an email message with optional attachments, CC/BCC recipients, and custom storage duration.

POST /api/mail/send

Description

The /api/mail/send endpoint allows you to compose and send email messages through the QMail network. You can include multiple recipients, CC and BCC fields, attach files, and specify how long the message should be stored on the network.

Content Types Supported

This endpoint accepts both application/json for text-only messages and multipart/form-data for messages with file attachments. When using JSON, attachments should be referenced by their file IDs or paths on the server.

Request Body (JSON)

Send a JSON payload with the following structure:

Parameter Type Required Description
to array of strings Yes List of recipient email addresses (QMail addresses or external emails).
cc array of strings No List of CC (carbon copy) recipient addresses.
bcc array of strings No List of BCC (blind carbon copy) recipient addresses.
subject string Yes Email subject line.
body string Yes Email message body (supports plain text or HTML).
attachments array of strings No Array of file paths or file IDs to attach to the email.
storage_weeks integer No Number of weeks to store the message on the network (default: 4, max: 52).

Example Request Body

{
  "to": ["[email protected]", "[email protected]"],
  "cc": ["[email protected]"],
  "bcc": ["[email protected]"],
  "subject": "Project Update",
  "body": "Hi team,\n\nHere's the latest update on our project...",
  "attachments": ["/uploads/report.pdf", "/uploads/chart.png"],
  "storage_weeks": 8
}

Response

Returns a 202 Accepted response indicating the message has been queued for sending.

Response Properties

status string
Status of the request (typically "accepted").
task_id string
Unique identifier for tracking the send task.
message string
Human-readable status message.
file_count integer
Number of attachments included with the message.
estimated_cost number
Estimated CloudCoin cost for sending the message (including storage and attachments).

Example Response

{
  "status": "accepted",
  "task_id": "e7d8f9a0-b1c2-4d5e-6f7a-8b9c0d1e2f3a",
  "message": "Email queued for sending",
  "file_count": 2,
  "estimated_cost": 5.25
}

Try It Out

Examples

JavaScript (fetch)

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

async function sendEmail() {
    const payload = {
        to: ['[email protected]', '[email protected]'],
        cc: ['[email protected]'],
        bcc: [],
        subject: 'Project Update',
        body: 'Hi team,\n\nHere is the latest update...',
        attachments: [],
        storage_weeks: 8
    };

    try {
        const response = await fetch(`${API_BASE}/mail/send`, {
            method: 'POST',
            headers: {
                'Content-Type': 'application/json'
            },
            body: JSON.stringify(payload)
        });

        const result = await response.json();

        if (response.ok) {
            console.log('Email sent successfully!');
            console.log('Task ID:', result.task_id);
            console.log('Estimated cost:', result.estimated_cost);
        } else {
            console.error('Failed to send email:', result.message);
        }
    } catch (error) {
        console.error('Error sending email:', error);
    }
}

sendEmail();

cURL

curl -X POST "http://localhost:8080/api/mail/send" \
  -H "Content-Type: application/json" \
  -d '{
    "to": ["[email protected]", "[email protected]"],
    "cc": ["[email protected]"],
    "bcc": [],
    "subject": "Project Update",
    "body": "Hi team,\n\nHere is the latest update...",
    "attachments": [],
    "storage_weeks": 8
  }'

Python

import requests
import json

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

def send_email():
    payload = {
        'to': ['[email protected]', '[email protected]'],
        'cc': ['[email protected]'],
        'bcc': [],
        'subject': 'Project Update',
        'body': 'Hi team,\n\nHere is the latest update...',
        'attachments': [],
        'storage_weeks': 8
    }

    try:
        response = requests.post(
            f'{API_BASE}/mail/send',
            headers={'Content-Type': 'application/json'},
            json=payload
        )

        result = response.json()

        if response.ok:
            print('Email sent successfully!')
            print(f'Task ID: {result["task_id"]}')
            print(f'Estimated cost: {result["estimated_cost"]}')
        else:
            print(f'Failed to send email: {result["message"]}')

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

send_email()