/api/qmail/attachments
GETList all attachments for a specific email.
GET /api/qmail/attachments
Description
The GET /api/qmail/attachments endpoint retrieves metadata about all attachments associated with a specific email. Each attachment entry includes the filename, file extension, size, storage mode, and a flag indicating whether the file type is potentially dangerous.
Dangerous File Detection
Attachments with potentially dangerous extensions (exe, bat, cmd, scr, vbs, pif, com, js, wsf, msi, dll, ps1, reg) will include a "dangerous": true flag in their metadata. Filenames are automatically sanitized to prevent path traversal attacks.
Parameters
Send as query parameters:
| Parameter | Type | Required | Description |
|---|---|---|---|
email_id |
string | Required | The unique email identifier (32-character hexadecimal GUID). |
Response
Returns a JSON object with an array of attachment metadata.
Response Properties
success
boolean
Indicates whether the operation completed successfully.
count
integer
Total number of attachments for this email.
attachments
array
Array of attachment metadata objects.
attachment_id
integer
Unique ID for this attachment.
name
string
Sanitized filename of the attachment.
extension
string
File extension (e.g., "pdf", "jpg").
storage_mode
integer
0 = internal (DB blob), 1 = external (file on disk).
size_bytes
integer
Size of the attachment in bytes.
dangerous
boolean
Present and
true if the file extension is potentially dangerous.
file_path
string
Present for external storage mode attachments. Path to the file on disk.
Example Success Response
{
"success": true,
"count": 2,
"attachments": [
{
"attachment_id": 1,
"name": "invoice.pdf",
"extension": "pdf",
"storage_mode": 0,
"size_bytes": 245760
},
{
"attachment_id": 2,
"name": "script.exe",
"extension": "exe",
"storage_mode": 0,
"size_bytes": 102400,
"dangerous": true
}
]
}Example Error Response (400 Bad Request)
{
"success": false,
"message": "Missing or invalid 'email_id' parameter (32 hex chars required)"
}Try It Out
Examples
cURL
curl -X GET "http://localhost:8080/api/qmail/attachments?email_id=a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6"JavaScript (async/await)
const API_HOST = 'http://localhost:8080';
async function listAttachments(emailId) {
try {
const response = await fetch(
`${API_HOST}/api/qmail/attachments?email_id=${emailId}`
);
const result = await response.json();
if (result.success) {
console.log(`Found ${result.count} attachment(s)`);
result.attachments.forEach(att => {
console.log(` ${att.name} (${att.size_bytes} bytes)`);
if (att.dangerous) console.log(' WARNING: dangerous file type');
});
} else {
console.error('Error:', result.message);
}
return result;
} catch (error) {
console.error('Error listing attachments:', error);
}
}
listAttachments('a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6');Python
import requests
API_HOST = 'http://localhost:8080'
def list_attachments(email_id):
response = requests.get(
f'{API_HOST}/api/qmail/attachments',
params={'email_id': email_id}
)
result = response.json()
if result.get('success'):
print(f"Found {result['count']} attachment(s)")
for att in result['attachments']:
print(f" {att['name']} ({att['size_bytes']} bytes)")
if att.get('dangerous'):
print(' WARNING: dangerous file type')
else:
print(f"Error: {result.get('message')}")
return result
list_attachments('a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6')Related Endpoints
/api/qmail/attachment/download
Download a specific attachment as binary data or retrieve its metadata.