REST API to mark mail messages as read/unread

Feature Request: REST API to Mark Mail Messages as Read/Unread

Description

The Mail app REST API currently supports reading messages and their metadata, but does not expose an endpoint to change the \Seen flag (mark as read/unread) via REST. Users must either:

1. Use the web UI (click the envelope icon or swipe in the app)
2. Use IMAP STORE \Seen directly (requires IMAP access to the mail server)

For integrations, automation pipelines, and MCP servers that operate via REST API, the absence of a read/unread mutation endpoint is a significant gap.

Proposed API

Add a new endpoint (or extend an existing one) following Nextcloud's API conventions:

POST /apps/mail/api/v{version}/folders/{folderId}/messages/{messageId}/flags

Body:
{
  "flags": ["\\Seen"]          // mark as read
  // or
  "flags": []                   // mark as unread
}

Alternatively, a PATCH on the message resource:

PATCH /apps/mail/api/v{version}/folders/{folderId}/messages/{messageId}

Body:
{
  "flagSeen": true
}

Response

• 200 OK — flag updated successfully
• 404 — message not found
• 403 — insufficient permissions

Rationale

• Enables MCP servers and third-party integrations to properly manage email state after processing
• Consistent with existing POST-based mutations in the Mail API (e.g., creating messages, moving to folders)
• Parity with IMAP STORE command — the underlying implementation would do exactly this
• The nc_mail_mark_as_read tool in cbcoutinho/nextcloud-mcp-server depends on this endpoint

Impact

• MCP ecosystem: Enables proper email processing workflows where messages are automatically marked as read after being handled
• Automation: Allows pipelines to clean up after processing emails without requiring IMAP access
• Consistency: The Mail app already tracks read state internally; the REST API just needs to expose mutation

Priority

Medium-High — blocks full email automation for API-driven clients (MCP, n8n, custom integrations).

Start by tracing the existing Mail REST API mutation endpoints, especially the POST-based operations for creating messages and moving them to folders, then identify how the app currently tracks the \Seen flag. Define one consistent endpoint for setting read and unread state, including the proposed success and error responses, and verify it through API tests covering both flag values.