Feature request: REST API to mark mail messages as read/unread

[TheNovaNodes]

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).

[kesselb]

Thanks, that sounds like a nice feature 👍

[odzhychko]

New API sounds good. When implementing, we should check that it is consistent with the other REST API we provide.

[olivgui360]

I am currently working on integrating nextcloud with openwebUI (tables, files, deck, contacts, tasks, calendar and mails so far), developing tools to make the bridge between API, IMAP/SMTP. It has been quite simple where the API is rich but I am meeting limitations with nextcloud mail API. I had to install a dovecot mirror server to have a decent search across diverse mailboxes, managing flags and folders with AI agents.
I would be interested following-up this potential development to see where it goes as this would provide a great door to agents for managing multiple mailboxes.