/mail/{id}

GET

Retrieve detailed metadata for a specific email by its unique identifier.

GET /api/mail/{id}

Description

The /mail/{id} endpoint retrieves the complete metadata for a specific email message. This includes sender and recipient information, subject, timestamp, read status, attachments list, and other email properties.

Email ID Format

Email IDs are 32-character hexadecimal strings (128-bit identifiers). You can obtain email IDs from the /mail/list endpoint.

Path Parameters

Parameter Type Required Description
id string Yes The unique email identifier. Must be a 32-character hexadecimal string.

Response

Returns a JSON object containing complete email metadata.

Response Properties

id string
The unique email identifier.
from string
The sender's email address.
to array of strings
An array of recipient email addresses.
cc array of strings
An array of CC recipient email addresses (may be empty).
subject string
The email subject line.
timestamp string
ISO 8601 formatted timestamp of when the email was sent/received.
is_read boolean
Whether the email has been marked as read.
folder string
The folder containing this email (inbox, sent, drafts, trash).
attachments array of objects
An array of attachment metadata. Each object contains: file_type, filename, size.
body_preview string
A preview snippet of the email body (first 200 characters).

Example Response

{
  "id": "a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6",
  "from": "[email protected]",
  "to": ["[email protected]"],
  "cc": ["[email protected]"],
  "subject": "Q4 Budget Report",
  "timestamp": "2025-12-20T14:30:00Z",
  "is_read": false,
  "folder": "inbox",
  "attachments": [
    {
      "file_type": 10,
      "filename": "budget_report_q4.pdf",
      "size": 245678
    },
    {
      "file_type": 11,
      "filename": "spreadsheet.xlsx",
      "size": 89234
    }
  ],
  "body_preview": "Hi Bob, Please find attached the Q4 budget report for your review. Let me know if you have any questions or need additional details..."
}

Try It Out

Enter a 32-character hexadecimal email ID
http://localhost:8080/api/mail/{id}

Examples

JavaScript (async/await)

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

async function getEmailDetails(emailId) {
    try {
        const response = await fetch(`${API_BASE}/mail/${emailId}`);
        const email = await response.json();

        console.log('Email Details:');
        console.log(`From: ${email.from}`);
        console.log(`To: ${email.to.join(', ')}`);
        console.log(`Subject: ${email.subject}`);
        console.log(`Read: ${email.is_read}`);
        console.log(`Attachments: ${email.attachments.length}`);

        if (email.attachments.length > 0) {
            console.log('Attachment list:');
            email.attachments.forEach(att => {
                console.log(`  - ${att.filename} (${att.size} bytes)`);
            });
        }
    } catch (error) {
        console.error('Error fetching email:', error);
    }
}

getEmailDetails(emailId);

cURL

curl -X GET "http://localhost:8080/api/mail/a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6" \
  -H "Accept: application/json"

Python

import requests

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

def get_email_details(email_id):
    response = requests.get(f'{API_BASE}/mail/{email_id}')
    email = response.json()

    print('Email Details:')
    print(f"From: {email['from']}")
    print(f"To: {', '.join(email['to'])}")
    print(f"Subject: {email['subject']}")
    print(f"Read: {email['is_read']}")
    print(f"Attachments: {len(email['attachments'])}")

    if email['attachments']:
        print('Attachment list:')
        for att in email['attachments']:
            print(f"  - {att['filename']} ({att['size']} bytes)")

get_email_details(email_id)

Related Endpoints

/mail/list

List emails from a folder to obtain email IDs for use with this endpoint.

View Details

/mail/download/{id}

Download the email body or attachments after retrieving email metadata.

View Details