/mail/{id}

DELETE

Permanently delete an email message from the system.

DELETE /api/mail/{id}

Description

The DELETE /mail/{id} endpoint permanently removes an email from the system. Unlike moving to trash, this operation cannot be undone. The email and all its attachments are completely deleted.

Permanent Deletion Warning

This operation is irreversible. Once deleted, the email cannot be recovered. Consider moving emails to the trash folder first (using the move endpoint) to allow for recovery before permanent deletion.

Path Parameters

Parameter Type Required Description
id string Yes The unique email identifier (32-character hexadecimal string).

Response

Returns a JSON object confirming the deletion.

Response Properties

status string
Operation status. Typically "success" or "error".
email_id string
The ID of the email that was deleted.
message string
A human-readable confirmation message.

Example Success Response

{
  "status": "success",
  "email_id": "a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6",
  "message": "Email permanently deleted"
}

Example Error Response

{
  "status": "error",
  "email_id": "a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6",
  "message": "Email not found"
}

Try It Out

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

Executing this request will permanently delete the email. This action cannot be undone.

Examples

JavaScript (async/await)

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

async function deleteEmail(emailId) {
    // Confirm before deleting
    if (!confirm('Are you sure you want to permanently delete this email?')) {
        return;
    }

    try {
        const response = await fetch(`${API_BASE}/mail/${emailId}`, {
            method: 'DELETE',
            headers: {
                'Accept': 'application/json'
            }
        });

        const result = await response.json();

        if (result.status === 'success') {
            console.log(`Email ${result.email_id} deleted successfully`);
            console.log(result.message);
        } else {
            console.error(`Failed to delete email: ${result.message}`);
        }

        return result;
    } catch (error) {
        console.error('Error deleting email:', error);
    }
}

deleteEmail(emailId);

cURL

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

Python

import requests

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

def delete_email(email_id):
    # You might want to add confirmation logic here
    response = requests.delete(f'{API_BASE}/mail/{email_id}')
    result = response.json()

    if result['status'] == 'success':
        print(f"Email {result['email_id']} deleted successfully")
        print(result['message'])
    else:
        print(f"Failed to delete email: {result['message']}")

    return result

delete_email(email_id)

Use Cases

Cleaning Up Trash

Use this endpoint to permanently delete emails that have been in the trash folder for a certain period (e.g., 30 days), freeing up storage space.

Bulk Deletion

Combine with the list endpoint to identify and delete multiple emails matching specific criteria (e.g., spam, old drafts).

Privacy Compliance

Implement GDPR "right to be forgotten" by permanently deleting all emails associated with a user account.

Related Endpoints

/mail/{id}/move

For a reversible deletion, move the email to trash instead of permanently deleting it.

View Details

/mail/list

List emails from the trash folder to identify candidates for permanent deletion.

View Details