/api/qmail/attachment/download

GET

Download a specific email attachment or retrieve its metadata.

GET /api/qmail/attachment/download

Description

The GET /api/qmail/attachment/download endpoint serves a specific email attachment. By default it returns the raw binary file data with the appropriate Content-Type header (e.g., image/jpeg, application/pdf). Pass ?info=1 to get JSON metadata about the attachment instead.

Binary Response

By default, this endpoint returns raw binary data with the appropriate Content-Type header. Pass ?info=1 to get JSON metadata about the attachment instead of downloading it.

Security Verification

The endpoint verifies that the attachment belongs to the specified email. Attempting to access an attachment from a different email will return a 403 Forbidden error.

Parameters

Send as query parameters:

Parameter Type Required Description
email_id string Required The unique email identifier (32-character hexadecimal GUID).
attachment_id integer Required The numeric ID of the attachment to download (from the attachments list endpoint).
info string Optional Set to "1" to return JSON metadata instead of binary data.

Response

Binary Mode (default)

Returns raw file bytes with Content-Type set to the appropriate MIME type (e.g., application/pdf, image/png, image/jpeg, text/plain, application/zip). HTTP status 200.

Info Mode (?info=1)

Returns JSON metadata about the attachment.

Info Response Properties

success boolean
Indicates whether the operation completed successfully.
attachment_id integer
The unique ID of the attachment.
name string
Sanitized filename of the attachment.
extension string
File extension.
size_bytes integer
Size of the attachment in bytes.
storage_mode integer
0 = internal (DB blob), 1 = external (file on disk).
dangerous boolean
Present and true if the file type is potentially dangerous.
warning string
Present for dangerous files: "This file type is potentially dangerous. Exercise caution."

Example Info Response

{
  "success": true,
  "attachment_id": 1,
  "name": "invoice.pdf",
  "extension": "pdf",
  "size_bytes": 245760,
  "storage_mode": 0
}

Example Error Response (403 Forbidden)

{
  "success": false,
  "message": "Attachment does not belong to the specified email"
}

Example Error Response (404 Not Found)

{
  "success": false,
  "message": "Attachment not found"
}

Try It Out

Enter a 32-character hexadecimal email ID
http://localhost:8080/api/qmail/attachment/download?email_id=&attachment_id=

Examples

cURL

# Download attachment as binary file
curl -o invoice.pdf "http://localhost:8080/api/qmail/attachment/download?email_id=a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6&attachment_id=1"

# Get attachment metadata as JSON
curl "http://localhost:8080/api/qmail/attachment/download?email_id=a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6&attachment_id=1&info=1"

JavaScript (async/await)

const API_HOST = 'http://localhost:8080';

// Download as binary blob
async function downloadAttachment(emailId, attachmentId) {
    const url = `${API_HOST}/api/qmail/attachment/download` +
        `?email_id=${emailId}&attachment_id=${attachmentId}`;

    const response = await fetch(url);
    const blob = await response.blob();

    // Create download link
    const a = document.createElement('a');
    a.href = URL.createObjectURL(blob);
    a.download = 'attachment';
    a.click();
}

// Get metadata only
async function getAttachmentInfo(emailId, attachmentId) {
    const url = `${API_HOST}/api/qmail/attachment/download` +
        `?email_id=${emailId}&attachment_id=${attachmentId}&info=1`;

    const response = await fetch(url);
    const info = await response.json();
    console.log(`Name: ${info.name}, Size: ${info.size_bytes} bytes`);
    return info;
}

downloadAttachment('a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6', 1);

Python

import requests

API_HOST = 'http://localhost:8080'

def download_attachment(email_id, attachment_id, save_path='attachment'):
    """Download attachment binary data and save to file."""
    response = requests.get(
        f'{API_HOST}/api/qmail/attachment/download',
        params={'email_id': email_id, 'attachment_id': attachment_id}
    )
    with open(save_path, 'wb') as f:
        f.write(response.content)
    print(f"Saved {len(response.content)} bytes to {save_path}")

def get_attachment_info(email_id, attachment_id):
    """Get attachment metadata as JSON."""
    response = requests.get(
        f'{API_HOST}/api/qmail/attachment/download',
        params={'email_id': email_id, 'attachment_id': attachment_id, 'info': '1'}
    )
    info = response.json()
    print(f"Name: {info['name']}, Size: {info['size_bytes']} bytes")
    return info

# Download binary
download_attachment('a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6', 1, 'invoice.pdf')

# Get metadata
get_attachment_info('a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6', 1)

Related Endpoints

/api/qmail/attachments

List all attachments for an email to get attachment IDs.

View Details

/api/qmail/read

Read the full email including body text.

View Details