/api/qmail/db/messages/set-star

GET POST

Toggle the starred flag on an email message.

GET /api/qmail/db/messages/set-star?email_id={email_id}&starred=true

Description

The POST /api/qmail/db/messages/set-star endpoint toggles the starred (flagged) status of a specific email. Starred emails are typically used to mark important messages for quick access. By default, calling this endpoint stars the email; pass starred=false or starred=0 to remove the star.

Idempotent Operation

Starring an already-starred email (or unstarring an already-unstarred email) will succeed without error. The response always reflects the current state after the operation.

Parameters

Send as form-encoded POST body or query parameters:

Parameter	Type	Required	Description
`email_id`	string	Required	The unique email identifier (32-character hexadecimal GUID).
`starred`	string	Optional	Set to `"true"` (default) to star the email, or `"0"` / `"false"` to unstar it.

Response

Returns a JSON object confirming the updated star status.

Response Properties

success boolean

Indicates whether the operation completed successfully.

email_id string

The 32-character hex GUID of the email that was updated.

is_starred boolean

The current starred state of the email after the operation.

Example Success Response (Starred)

{
  "success": true,
  "email_id": "a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6",
  "is_starred": true
}

Example Success Response (Unstarred)

{
  "success": true,
  "message": "Star updated",
  "email_id": "a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6",
  "is_starred": false
}

Example Error Response (400 Bad Request)

{
  "error": true,
  "message": "Missing required parameter: starred",
  "code": 400
}

Example Error Response (404 Not Found)

{
  "error": true,
  "message": "Email not found",
  "code": 404
}

Try It Out

Examples

cURL

# Star an email (GET — easy browser/devtool testing)
curl "http://localhost:8082/api/qmail/db/messages/set-star?email_id=a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6&starred=true"

# Unstar an email (GET)
curl "http://localhost:8082/api/qmail/db/messages/set-star?email_id=a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6&starred=false"

# Star an email (canonical POST)
curl -X POST "http://localhost:8082/api/qmail/db/messages/set-star" \
  -d "email_id=a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6" \
  -d "starred=true"

# Unstar an email (canonical POST)
curl -X POST "http://localhost:8082/api/qmail/db/messages/set-star" \
  -d "email_id=a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6" \
  -d "starred=false"

JavaScript (async/await)

const API_HOST = 'http://localhost:8082/api';

async function toggleStar(emailId, starred = true) {
    try {
        const params = new URLSearchParams();
        params.append('email_id', emailId);
        params.append('starred', starred.toString());

        const response = await fetch(`${API_HOST}/qmail/db/messages/set-star`, {
            method: 'POST',
            headers: {
                'Content-Type': 'application/x-www-form-urlencoded'
            },
            body: params.toString()
        });

        const result = await response.json();

        if (response.ok && result.success) {
            console.log(`Email ${result.email_id} is now ${result.is_starred ? 'starred' : 'unstarred'}`);
        } else {
            console.error(`Error: ${result.message} (HTTP ${result.code ?? response.status})`);
            if (result.detail) {
                console.error(`Detail: ${result.detail}`);
            }
        }

        return result;
    } catch (error) {
        console.error('Error toggling star:', error);
    }
}

// Star an email
toggleStar('a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6', true);

// Unstar an email
// toggleStar('a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6', false);

Python

import requests

API_HOST = 'http://localhost:8082/api'

def toggle_star(email_id, starred=True):
    response = requests.post(
        f'{API_HOST}/qmail/db/messages/set-star',
        data={
            'email_id': email_id,
            'starred': 'true' if starred else 'false'
        }
    )

    result = response.json()

    if result.get('success'):
        status = 'starred' if result['is_starred'] else 'unstarred'
        print(f"Email {result['email_id']} is now {status}")
    else:
        print(f"Error: {result.get('error')}")

    return result

# Star an email
toggle_star('a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6', True)

# Unstar an email
# toggle_star('a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6', False)

Related Endpoints

/api/qmail/db/messages/set-read

Toggle the read/unread status of an email message.

View Details

/api/qmail/db/messages/list

List emails to find starred messages or candidates for starring.

View Details

/api/qmail/db/messages/get

Get full email details including the current starred status.

View Details