/api/qmail/read
GETRead a single email by ID, returning its full contents.
Description
The /api/qmail/read endpoint retrieves the full contents of a single email by its unique identifier. This includes the subject, sender, timestamps, folder, starred status, and the complete email body.
Side Effect: Marks as Read
Calling this endpoint automatically marks the email as read. The is_read field in the response will always be true after a successful call. There is no need to make a separate request to update read status.
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
email_id |
string | Yes | The unique email identifier. Must be a 32-character hexadecimal GUID string. |
Response
Returns a JSON object containing the full email contents and metadata.
Response Properties
success
boolean
Indicates whether the request was successful.
true on success.
email_id
string
The 32-character hex GUID of the email.
subject
string
The subject line of the email.
sender_sn
integer
The serial number of the sender.
received_timestamp
integer (int64)
Unix timestamp (in seconds) of when the email was received.
is_read
boolean
Always
true after reading. The email is automatically marked as read by this endpoint.
is_starred
boolean
Whether the email has been starred/flagged by the user.
folder
integer
The numeric folder ID where the email is stored.
body
string
The full email body content.
body_length
integer
The length of the email body in bytes.
Example Success Response
{
"success": true,
"email_id": "a1b2c3d4e5f67890a1b2c3d4e5f67890",
"subject": "Q4 Budget Report",
"sender_sn": 1042,
"received_timestamp": 1706140800,
"is_read": true,
"is_starred": false,
"folder": 0,
"body": "Hi Bob,\n\nPlease find attached the Q4 budget report for your review.\n\nBest regards,\nAlice",
"body_length": 88
}Error Responses
// 400 Bad Request - Missing email_id
{
"success": false,
"message": "Missing required parameter: email_id"
}
// 400 Bad Request - Invalid format
{
"success": false,
"message": "Invalid email_id format"
}
// 404 Not Found - Email does not exist
{
"success": false,
"message": "Email not found"
}Try It Out
Examples
cURL
# Read a single email by ID (also marks it as read)
curl -X GET "http://localhost:8080/api/qmail/read?email_id=a1b2c3d4e5f67890a1b2c3d4e5f67890"JavaScript (async/await)
const API_BASE = 'http://localhost:8080/api';
const emailId = 'a1b2c3d4e5f67890a1b2c3d4e5f67890';
async function readEmail(emailId) {
try {
const response = await fetch(
`${API_BASE}/qmail/read?email_id=${emailId}`
);
const result = await response.json();
if (result.success) {
console.log(`Subject: ${result.subject}`);
console.log(`From SN: ${result.sender_sn}`);
console.log(`Starred: ${result.is_starred}`);
console.log(`Body (${result.body_length} bytes):`);
console.log(result.body);
} else {
console.error('Failed to read email:', result.message);
}
return result;
} catch (error) {
console.error('Error reading email:', error);
}
}
readEmail(emailId);Python
import requests
API_BASE = 'http://localhost:8080/api'
email_id = 'a1b2c3d4e5f67890a1b2c3d4e5f67890'
def read_email(email_id):
response = requests.get(
f'{API_BASE}/qmail/read',
params={'email_id': email_id}
)
result = response.json()
if result.get('success'):
print(f"Subject: {result['subject']}")
print(f"From SN: {result['sender_sn']}")
print(f"Starred: {result['is_starred']}")
print(f"Body ({result['body_length']} bytes):")
print(result['body'])
else:
print(f"Failed to read email: {result.get('message')}")
return result
read_email(email_id)Related Endpoints
/api/qmail/inbox
List emails in a folder to discover email IDs for use with this endpoint.