/mail/{id}/move

PUT

Move an email from one folder to another.

PUT /api/mail/{id}/move

Description

The /mail/{id}/move endpoint allows you to move an email between mailbox folders (inbox, sent, drafts, trash). This is useful for organizing emails, archiving messages, or implementing a trash/restore functionality.

Folder Management

Valid folder names are: inbox, sent, drafts, and trash. Moving to trash is a soft delete - use the DELETE endpoint for permanent deletion.

Path Parameters

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

Request Body

The request must include a JSON body specifying the destination folder.

Parameter Type Required Description
folder string Yes The destination folder. Must be one of: inbox, sent, drafts, trash.

Example Request Body

{
  "folder": "trash"
}

Response

Returns a JSON object confirming the move operation and showing both the previous and new folder locations.

Response Properties

status string
Operation status. Typically "success".
email_id string
The ID of the email that was moved.
folder string
The new folder location of the email.
previous_folder string
The folder where the email was located before the move.

Example Response

{
  "status": "success",
  "email_id": "a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6",
  "folder": "trash",
  "previous_folder": "inbox"
}

Try It Out

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

Examples

JavaScript (async/await)

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

async function moveEmailToFolder(emailId, folder) {
    try {
        const response = await fetch(`${API_BASE}/mail/${emailId}/move`, {
            method: 'PUT',
            headers: {
                'Content-Type': 'application/json'
            },
            body: JSON.stringify({ folder: folder })
        });

        const result = await response.json();

        if (result.status === 'success') {
            console.log(`Email moved from "${result.previous_folder}" to "${result.folder}"`);
        }

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

// Move email to trash
moveEmailToFolder(emailId, 'trash');

// Restore from trash to inbox
// moveEmailToFolder(emailId, 'inbox');

// Move to drafts
// moveEmailToFolder(emailId, 'drafts');

cURL

# Move email to trash
curl -X PUT "http://localhost:8080/api/mail/a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6/move" \
  -H "Content-Type: application/json" \
  -d '{"folder": "trash"}'

# Restore from trash to inbox
curl -X PUT "http://localhost:8080/api/mail/a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6/move" \
  -H "Content-Type: application/json" \
  -d '{"folder": "inbox"}'

Python

import requests

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

def move_email_to_folder(email_id, folder):
    response = requests.put(
        f'{API_BASE}/mail/{email_id}/move',
        json={'folder': folder}
    )

    result = response.json()

    if result['status'] == 'success':
        print(f"Email moved from \"{result['previous_folder']}\" to \"{result['folder']}\"")

    return result

# Move email to trash
move_email_to_folder(email_id, 'trash')

# Restore from trash to inbox
# move_email_to_folder(email_id, 'inbox')

# Move to drafts
# move_email_to_folder(email_id, 'drafts')

Related Endpoints

/mail/{id}

Get email details including current folder location before moving.

View Details

/mail/{id}

Permanently delete an email instead of moving it to trash.

View Details (DELETE)