librus-python-api 1.0.3__tar.gz → 1.3.0__tar.gz

{librus_python_api-1.0.3 → librus_python_api-1.3.0}/API.md

@@ -191,7 +191,45 @@ source)` with an aware UTC timestamp.
   selection. It reuses only that view's cache; averages and undated summaries
   remain outside the window.
 
-The observation card ("Karta spostrzeżeń") shown on some grades pages is not
+### School-year archive (1.3.0)
+
+`school_year_archive(*, budget=None, max_age_seconds=0.0)` returns
+`SchoolYearArchive(identity, years, achievements, observation)`. It performs one
+read-only GET for all earlier years, with the same per-login cache, coalescing,
+budgets and safe-read session recovery as `announcements()`. There is no year
+selection or chart request. This is separate from the modern message archive.
+
+- `years` contains `ArchiveYear` in page order: `class_name`, `school_year`,
+  `first_year`, `subjects`, `descriptive`, two raw behaviour fields and `absences`.
+- Each `ArchiveSubject(subject, marks)` has `ArchiveMarks(first_semester,
+  second_semester, year_end)`. Empty text and `-` remain distinct. `year_end` is
+  not asserted to equal `SubjectGradeSummary.annual`.
+- `ArchiveDescriptive(label, text)` keeps whole-year text, with explicit BR
+  boundaries as newlines. Source whitespace is normalized.
+- `behaviour_first_semester` and `behaviour_second_semester_and_year_end` retain
+  positional text. Populated behaviour semantics have not been observed.
+- `ArchiveAbsences(unexcused, excused, late)` contains `ArchiveCounts` with the
+  same three period names. Counts are rendered integers, never summed or repaired.
+- `achievements` contains `ArchiveAchievement(day, class_name, category, text)`;
+  `day` is a civil `date`. A header-only achievements table yields an empty tuple.
+
+All archive types are root exports. School text and record containers are omitted
+from reprs; the page's student-name header does not enter archive records.
+Limits: 16 unique consecutive school-year pairs, 128 subject rows, 32 descriptive
+rows, 256 achievements, 1024 characters per short field, 65536 per long text
+cell and 262144 total rendered characters, plus the shared transport/tree bounds.
+
+The observed `Brak danych` information notice returns empty `years` and
+`achievements`. Missing tables without that explicit marker still raise `PARSE`;
+an empty notice combined with data tables is rejected. Repeated school years
+(including a class-change layout) are ambiguous and raise `PARSE`. Unknown
+geometry/markup raises `UNSUPPORTED_CAPABILITY`; bounds raise `LIMIT`, never
+partial success. Consumers must handle these states before exposing the read.
+See [archive evidence and limitations](contracts/grades.md#school-year-archive-130).
+
+The observed grade-detail page added no fields beyond the list tooltip, so
+there is no separate per-grade detail request. This finding is limited to the
+observed layout. The observation card ("Karta spostrzeżeń") shown on some grades pages is not
 read yet.
 
 ## Attendance
@@ -399,13 +437,45 @@ redirects, fallback, post-send lookup or implicit reauthentication. Cancel/shutd
 propagate normally with an inspectable outcome after joined cleanup, as below.
 Modern list/content reads do not reconcile durable UNKNOWN send history.
 
-- `modern_messages_page(folder=RECEIVED, *, page=1, page_size=10, budget=None,
-  max_age_seconds=0)` returns `ModernMessagesPage`. Pages are one-based. This GET
-  returns summaries only; sent read status can be unknown.
+- `modern_messages_page(folder=RECEIVED, *, page=1, page_size=10, archived=False,
+  budget=None, max_age_seconds=0)` returns `ModernMessagesPage`. Pages are
+  one-based. This GET returns summaries only; sent read status can be unknown.
 - `modern_messages(folder=RECEIVED, *, cursor=None, page_size=50, max_pages=4,
-  limit=128, budget=None, max_age_seconds=0)` returns `ModernMessages` with explicit
-  truncation, duplicate counts and account/folder/page-size-bound continuation.
+  limit=128, archived=False, budget=None, max_age_seconds=0)` returns
+  `ModernMessages` with explicit truncation, duplicate counts and
+  account/folder/mailbox/page-size-bound continuation.
   Cursor drift and later-page errors never return partial output.
+- `archived=True` (1.1.0) lists the archive mailbox instead of the current one.
+  Pages, collections, cursors and references carry `archived`; a cursor never
+  continues the other mailbox. Archived content opens raise
+  `UNSUPPORTED_CAPABILITY` because no archived content route or mark-read effect
+  is established. Archive pages and collections report the upstream
+  `archivingInProgress` status as `archiving_in_progress` (`None` for the
+  current mailbox). Live archives report `true` while listing normally, so it
+  is informational; before 1.2.1 it wrongly made every archive read
+  `UNSUPPORTED_CAPABILITY`.
+- `modern_correspondents(folder=RECEIVED, *, budget=None, max_age_seconds=0)`
+  (1.2.0) returns `ModernCorrespondents`: the senders (received) or receivers
+  (sent) the web app offers in its filter panel. Each `ModernCorrespondent` has
+  `first_name`, `last_name` (one may be empty, never both) and a login-bound
+  `ModernCorrespondentReference`.
+- `modern_messages_page()` and `modern_messages()` accept `correspondent=` (a
+  reference for the same folder and login) and, for the received folder,
+  `unread_only=True` (1.2.0). They send the web app's own `senderId`,
+  `receiverId` and `unreadOnly` filters. Results and cursors record the filter,
+  and a cursor never continues a differently filtered list. Filters on the
+  archive mailbox raise `UNSUPPORTED_CAPABILITY`; they were not observed there.
+- `modern_teacher_subjects(*, budget=None, max_age_seconds=0)` (1.2.0) returns
+  `ModernTeacherSubjects`: `ModernTeacherSubject(teacher_identifier, subject)`
+  pairs, one per subject a teacher teaches the student. Identical repeated rows
+  collapse to one (1.2.1). The identifier is the
+  teacher's modern account ID; it is informational and not a recipient reference.
+- `modern_unread_counts(*, budget=None, max_age_seconds=0)` (1.1.0) returns
+  `ModernUnreadCounts` with `current` and `archive` `ModernUnreadFolders`:
+  `inbox`, `notes`, `alerts`, `substitutions`, `absences`, `justifications` and
+  `trash`. It opens no message. A missing or invalid counter fails with `PARSE`;
+  unknown extra counters are ignored. Populated counter semantics beyond the
+  observed field names are not independently established.
   Page size is 1-50, page number 1-1,000, `max_pages` 1-8, `limit` 1-256 and
   cursor history at most 2,000 IDs. These are library bounds, not upstream maxima.
 - `modern_message_content(reference, *, allow_mark_read=False, budget=None,

{librus_python_api-1.0.3 → librus_python_api-1.3.0}/CHANGELOG.md

@@ -1,5 +1,69 @@
 # Changelog
 
+## 1.3.0 (2026-10-07) - School-year archive read
+
+Compatible minor release. Existing calls and results are unchanged.
+
+- Add `AccountClient.school_year_archive()` and frozen per-year records for
+  subject marks, descriptive text, raw behaviour cells, absence counts and
+  dated achievements. One read-only GET covers all earlier years without year
+  selection, chart requests or fetching grade-detail links.
+- Apply the shared account-isolated cache, coalescing, recovery and budgets.
+  Reject ambiguous tables, unknown markup and exceeded bounds without partial
+  output. Preserve empty marks and school-provided year-end values.
+- Add guarded weekly archive coverage with redacted year counts. Older pinned
+  libraries without the method skip this check. Installed live checks passed
+  on two parent logins, covering populated and explicit empty archives with
+  unchanged notification counters. Broader school-layout support is unqualified.
+- Recognize the observed `Brak danych` empty notice and the malformed HTML
+  chart container after the achievements footer. Nested tabular data still fails.
+- Record the #40 grade-detail finding: the observed page added no fields beyond
+  the list tooltip, so no separate grade-detail read is introduced.
+
+## 1.2.1 (2026-10-06) - Live fixes for archive listing and teacher subjects
+
+Compatible patch release found by the new pre-publication live check. 1.1.0 and
+1.2.0 were tagged but not published to PyPI because that check failed.
+
+- List the modern archive mailbox. Live archive pages report
+  `archivingInProgress: true` while listing normally, and 1.1.0/1.2.0 treated
+  that as unsupported, so every archive read failed. Archive pages and
+  collections now report it as `archiving_in_progress`; the current mailbox
+  still refuses the flag.
+- Collapse identical repeated rows in `modern_teacher_subjects()` instead of
+  failing with `PARSE`.
+
+## 1.2.0 (2026-10-06) - Modern correspondent filters and teacher subjects
+
+Compatible minor release. Existing calls and results are unchanged; new fields
+have defaults.
+
+- Add `modern_correspondents(folder)`, listing the senders (received) or
+  receivers (sent) the modern mailbox can be filtered by.
+- Filter `modern_messages_page()` and `modern_messages()` by `correspondent=`
+  and, for received messages, `unread_only=True`, using the web app's own
+  query filters. Pages, collections and cursors record the filter; a cursor
+  never continues a differently filtered list. The archive mailbox does not
+  accept filters.
+- Add `modern_teacher_subjects()`, pairing teachers' modern account IDs with
+  the subjects they teach the student.
+
+## 1.1.0 (2026-10-06) - Modern archive mailbox and unread counts
+
+Compatible minor release. Existing calls and results are unchanged; new fields
+have defaults.
+
+- List the modern archive mailbox (earlier school years) with
+  `modern_messages_page(..., archived=True)` and `modern_messages(...,
+  archived=True)`. Pages, collections, cursors and message references gain an
+  `archived` field (default `False`), and a cursor never continues the other
+  mailbox. Opening an archived message raises `UNSUPPORTED_CAPABILITY` until an
+  archived content route is established.
+- Add `modern_unread_counts()`, returning `ModernUnreadCounts` with current and
+  archive `ModernUnreadFolders` counters (inbox, notes, alerts, substitutions,
+  absences, justifications, trash) from the modern mailbox's own counter route.
+  It opens no message.
+
 ## 1.0.3 (2026-10-06) - Notification counts for parent logins
 
 Compatible patch release. The public library API is unchanged.

{librus_python_api-1.0.3 → librus_python_api-1.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: librus-python-api
-Version: 1.0.3
+Version: 1.3.0
 Summary: Independent bounded async Librus Synergia client
 Project-URL: Repository, https://github.com/krzysztofbury/librus-python-api
 Project-URL: Issues, https://github.com/krzysztofbury/librus-python-api/issues
@@ -26,6 +26,8 @@ Description-Content-Type: text/markdown
 
 # librus-python-api
 
+[![Weekly live check](https://github.com/krzysztofbury/librus-python-api/actions/workflows/live-check.yml/badge.svg?branch=main)](https://github.com/krzysztofbury/librus-python-api/actions/workflows/live-check.yml)
+
 Read grades, attendance, homework, timetables and messages from **Librus Synergia**
 in Python. This independent, asynchronous client handles login, session recovery,
 pagination and request limits, returning typed Python objects rather than HTML.
@@ -40,9 +42,10 @@ private ACLs. Windows installations include `pywin32` and `tzdata` automatically
 Network paths, reparse-point paths and unsafe storage permissions fail closed.
 See [platform requirements](contracts/persistence.md#windows-disk-boundary-25).
 
-**Status:** `1.0.x` freezes the documented native library API. It does not claim
-completed MCP cutover, production-state migration or universal live-school
-compatibility. Those consumer/live gates remain separate. School features depend
+**Status:** `1.3.0` adds a read-only school-year archive.
+Installed live checks passed for populated and empty
+archives on two parent logins; see [verification](VERIFICATION.md).
+The stable 1.x API does not guarantee every school layout. School features depend
 on what each account can access. See the [compatibility policy](API.md#compatibility-policy).
 See [limitations](#supported-features-and-limitations) below.
 
@@ -51,7 +54,7 @@ See [limitations](#supported-features-and-limitations) below.
 Install the exact release from PyPI after its gated publication completes:
 
 ```sh
-python -m pip install librus-python-api==1.0.3
+python -m pip install librus-python-api==1.3.0
 ```
 
 Pin the exact version qualified by your application. Before publication, use a
@@ -67,7 +70,7 @@ python -m pip install .
 To install a locally built wheel instead:
 
 ```sh
-python -m pip install ./dist/librus_python_api-1.0.3-py3-none-any.whl
+python -m pip install ./dist/librus_python_api-1.3.0-py3-none-any.whl
 ```
 
 No CLI or background process is installed: import the library in your own program.
@@ -148,6 +151,11 @@ attendance = await client.attendance_window(today.replace(day=1), today)
 
 # Permit reuse of this account's cached result for up to 60 seconds.
 announcements = await client.announcements(max_age_seconds=60)
+
+# Earlier school years, separate from the message archive (1.3.0).
+archive = await client.school_year_archive()
+for year in archive.years:
+    print(year.school_year, year.subjects)
 ```
 
 Collections expose named record tuples, for example `homework.items`, rather than
@@ -233,7 +241,7 @@ removed in 0.7.
 
 | Area | Available |
 | --- | --- |
-| School data | Profile, grades, attendance, timetable, announcements, agenda, homework and completed lessons |
+| School data | Profile, grades, school-year archive, attendance, timetable, announcements, agenda, homework and completed lessons |
 | Communication | Legacy/modern message lists and content, recipient discovery, bounded attachment streams and explicit sending |
 | Application workflows | Shared multi-account limits, caching, notification checkpoints, optional durable send/notification stores |
 

{librus_python_api-1.0.3 → librus_python_api-1.3.0}/README.md

@@ -1,5 +1,7 @@
 # librus-python-api
 
+[![Weekly live check](https://github.com/krzysztofbury/librus-python-api/actions/workflows/live-check.yml/badge.svg?branch=main)](https://github.com/krzysztofbury/librus-python-api/actions/workflows/live-check.yml)
+
 Read grades, attendance, homework, timetables and messages from **Librus Synergia**
 in Python. This independent, asynchronous client handles login, session recovery,
 pagination and request limits, returning typed Python objects rather than HTML.
@@ -14,9 +16,10 @@ private ACLs. Windows installations include `pywin32` and `tzdata` automatically
 Network paths, reparse-point paths and unsafe storage permissions fail closed.
 See [platform requirements](contracts/persistence.md#windows-disk-boundary-25).
 
-**Status:** `1.0.x` freezes the documented native library API. It does not claim
-completed MCP cutover, production-state migration or universal live-school
-compatibility. Those consumer/live gates remain separate. School features depend
+**Status:** `1.3.0` adds a read-only school-year archive.
+Installed live checks passed for populated and empty
+archives on two parent logins; see [verification](VERIFICATION.md).
+The stable 1.x API does not guarantee every school layout. School features depend
 on what each account can access. See the [compatibility policy](API.md#compatibility-policy).
 See [limitations](#supported-features-and-limitations) below.
 
@@ -25,7 +28,7 @@ See [limitations](#supported-features-and-limitations) below.
 Install the exact release from PyPI after its gated publication completes:
 
 ```sh
-python -m pip install librus-python-api==1.0.3
+python -m pip install librus-python-api==1.3.0
 ```
 
 Pin the exact version qualified by your application. Before publication, use a
@@ -41,7 +44,7 @@ python -m pip install .
 To install a locally built wheel instead:
 
 ```sh
-python -m pip install ./dist/librus_python_api-1.0.3-py3-none-any.whl
+python -m pip install ./dist/librus_python_api-1.3.0-py3-none-any.whl
 ```
 
 No CLI or background process is installed: import the library in your own program.
@@ -122,6 +125,11 @@ attendance = await client.attendance_window(today.replace(day=1), today)
 
 # Permit reuse of this account's cached result for up to 60 seconds.
 announcements = await client.announcements(max_age_seconds=60)
+
+# Earlier school years, separate from the message archive (1.3.0).
+archive = await client.school_year_archive()
+for year in archive.years:
+    print(year.school_year, year.subjects)
 ```
 
 Collections expose named record tuples, for example `homework.items`, rather than
@@ -207,7 +215,7 @@ removed in 0.7.
 
 | Area | Available |
 | --- | --- |
-| School data | Profile, grades, attendance, timetable, announcements, agenda, homework and completed lessons |
+| School data | Profile, grades, school-year archive, attendance, timetable, announcements, agenda, homework and completed lessons |
 | Communication | Legacy/modern message lists and content, recipient discovery, bounded attachment streams and explicit sending |
 | Application workflows | Shared multi-account limits, caching, notification checkpoints, optional durable send/notification stores |
 

{librus_python_api-1.0.3 → librus_python_api-1.3.0}/src/librus_python_api/__init__.py

@@ -16,6 +16,13 @@ from librus_python_api.models import (
     AgendaEvent,
     Announcement,
     Announcements,
+    ArchiveAbsences,
+    ArchiveAchievement,
+    ArchiveCounts,
+    ArchiveDescriptive,
+    ArchiveMarks,
+    ArchiveSubject,
+    ArchiveYear,
     AttachmentHeaders,
     AttachmentMetadata,
     Attendance,
@@ -65,6 +72,9 @@ from librus_python_api.models import (
     MessageTimestamp,
     MessagingBackend,
     ModernAccountData,
+    ModernCorrespondent,
+    ModernCorrespondentReference,
+    ModernCorrespondents,
     ModernIdentity,
     ModernMessageAttachment,
     ModernMessageAttachmentReference,
@@ -82,6 +92,10 @@ from librus_python_api.models import (
     ModernRecipientTypeReference,
     ModernRecipientTypes,
     ModernSendSubmission,
+    ModernTeacherSubject,
+    ModernTeacherSubjects,
+    ModernUnreadCounts,
+    ModernUnreadFolders,
     NotificationCategory,
     NotificationCount,
     NotificationCounts,
@@ -103,6 +117,7 @@ from librus_python_api.models import (
     SchoolAverage,
     SchoolDetail,
     SchoolReference,
+    SchoolYearArchive,
     SendResult,
     SendStatus,
     SendSubmission,
@@ -120,9 +135,17 @@ from librus_python_api.models import (
 from librus_python_api.sending import SendAttempt
 from librus_python_api.service import AccountClient, LibrusService
 
-__version__ = "1.0.3"
+__version__ = "1.3.0"
 
 __all__ = [
+    "ArchiveAbsences",
+    "ArchiveAchievement",
+    "ArchiveCounts",
+    "ArchiveDescriptive",
+    "ArchiveMarks",
+    "ArchiveSubject",
+    "ArchiveYear",
+    "SchoolYearArchive",
     "AccountContext",
     "MessagingBackend",
     "ModernAccountData",
@@ -135,6 +158,13 @@ __all__ = [
     "ModernMessageRecipientReceipt",
     "ModernMessages",
     "ModernMessagesCursor",
+    "ModernUnreadCounts",
+    "ModernCorrespondent",
+    "ModernCorrespondentReference",
+    "ModernCorrespondents",
+    "ModernTeacherSubject",
+    "ModernTeacherSubjects",
+    "ModernUnreadFolders",
     "ModernMessagesPage",
     "ModernMessageSummary",
     "ModernRecipient",

{librus_python_api-1.0.3 → librus_python_api-1.3.0}/src/librus_python_api/config.py

@@ -207,6 +207,60 @@ ENDPOINTS: Mapping[str, Endpoint] = MappingProxyType(
                 Evidence.INDEPENDENTLY_OBSERVED,
                 "messages",
             ),
+            Endpoint(
+                "modern_archive_messages_received",
+                "GET",
+                "/api/archive/inbox/messages",
+                SideEffect.NONE,
+                False,
+                Evidence.INDEPENDENTLY_OBSERVED,
+                "messages",
+            ),
+            Endpoint(
+                "modern_archive_messages_sent",
+                "GET",
+                "/api/archive/outbox/messages",
+                SideEffect.NONE,
+                False,
+                Evidence.INDEPENDENTLY_OBSERVED,
+                "messages",
+            ),
+            Endpoint(
+                "modern_unread_counts",
+                "GET",
+                "/api/inbox/unreadMessagesCount",
+                SideEffect.NONE,
+                False,
+                Evidence.INDEPENDENTLY_OBSERVED,
+                "messages",
+            ),
+            Endpoint(
+                "modern_senders",
+                "GET",
+                "/api/inbox/messages/senders",
+                SideEffect.NONE,
+                False,
+                Evidence.INDEPENDENTLY_OBSERVED,
+                "messages",
+            ),
+            Endpoint(
+                "modern_receivers",
+                "GET",
+                "/api/outbox/messages/receivers",
+                SideEffect.NONE,
+                False,
+                Evidence.INDEPENDENTLY_OBSERVED,
+                "messages",
+            ),
+            Endpoint(
+                "modern_teacher_subjects",
+                "GET",
+                "/api/receivers/student-subjects",
+                SideEffect.NONE,
+                False,
+                Evidence.INDEPENDENTLY_OBSERVED,
+                "messages",
+            ),
             Endpoint(
                 "modern_content_received",
                 "GET",
@@ -451,6 +505,14 @@ ENDPOINTS: Mapping[str, Endpoint] = MappingProxyType(
                 True,
                 Evidence.INDEPENDENTLY_OBSERVED,
             ),
+            Endpoint(
+                "school_year_archive",
+                "GET",
+                "/archiwum",
+                SideEffect.NONE,
+                True,
+                Evidence.INDEPENDENTLY_OBSERVED,
+            ),
             Endpoint(
                 "agenda",
                 "POST",
@@ -668,6 +730,35 @@ ANNOUNCEMENT_MAX_ITEMS = 256
 ANNOUNCEMENT_MAX_FIELD_LENGTH = 1024
 ANNOUNCEMENT_MAX_CONTENT_LENGTH = 65536
 ANNOUNCEMENT_MAX_TOTAL_TEXT_LENGTH = 262144
+
+# School-year archive (/archiwum): labels as rendered upstream, including the
+# absence spellings. Matching is case-insensitive and exact otherwise.
+ARCHIVE_TABLE_CLASSES = frozenset({"decorated"})
+ARCHIVE_ACHIEVEMENT_TABLE_CLASSES = frozenset({"decorated", "big", "center"})
+ARCHIVE_YEAR_PATTERN = (
+    r"Klasa: (?P<class_name>\S(?:.*\S)?) Rok: (?P<first>[0-9]{4})/(?P<second>[0-9]{4})"
+)
+ARCHIVE_PERIOD_LABELS = ("okres 1", "okres 2", "koniec roku")
+ARCHIVE_BEHAVIOUR_HEADING = "zachowanie"
+ARCHIVE_ABSENCES_HEADING = "nieobecności"
+ARCHIVE_ABSENCE_LABELS = MappingProxyType(
+    {
+        "nieusprawiedlione": "unexcused",
+        "usprawiedlione": "excused",
+        "spóźnienia": "late",
+    }
+)
+ARCHIVE_ACHIEVEMENT_HEADERS = ("data", "klasa", "kategoria", "osiągnięcie")
+ARCHIVE_YEAR_HEADER_TAGS = frozenset({"span", "b"})
+ARCHIVE_MAX_YEARS = 16
+ARCHIVE_MAX_SUBJECTS = 128
+ARCHIVE_MAX_DESCRIPTIVE = 32
+ARCHIVE_MAX_ACHIEVEMENTS = 256
+ARCHIVE_MAX_TEXT_LENGTH = 65536
+ARCHIVE_MAX_TOTAL_TEXT_LENGTH = 262144
+ARCHIVE_MAX_YEAR_HEADER_LENGTH = 1024 + len("Klasa:  Rok: 0000/0000")
+ARCHIVE_EMPTY_TITLE = "brak danych"
+ARCHIVE_EMPTY_BOX_CLASSES = frozenset({"warning-box", "information", "medium"})
 ANNOUNCEMENT_TABLE_CLASSES = frozenset(
     {"decorated", "big", "center", "printable", "margin-top"}
 )
@@ -878,17 +969,67 @@ def modern_directory_query(
 
 
 def modern_mailbox_query(
-    folder: MessageFolder, page: int, page_size: int
+    folder: MessageFolder,
+    page: int,
+    page_size: int,
+    *,
+    correspondent: str | None = None,
+    unread_only: bool = False,
 ) -> dict[str, str]:
+    """Page selection plus the web app's own sender/receiver/unread filters."""
     if (
         not isinstance(folder, MessageFolder)
         or type(page) is not int
         or not 1 <= page <= 1000
         or type(page_size) is not int
         or not 1 <= page_size <= 50
+        or type(unread_only) is not bool
+        or (unread_only and folder is not MessageFolder.RECEIVED)
+        or (
+            correspondent is not None
+            and (
+                type(correspondent) is not str
+                or re.fullmatch(r"[0-9]{1,64}", correspondent) is None
+            )
+        )
     ):
         raise LibrusError(ErrorKind.INVALID_INPUT)
-    return {"page": str(page), "limit": str(page_size)}
+    query = {}
+    if correspondent is not None:
+        query[MODERN_CORRESPONDENT_FILTERS[folder]] = correspondent
+    if unread_only:
+        query["unreadOnly"] = "1"
+    return query | {"page": str(page), "limit": str(page_size)}
+
+
+MODERN_MAILBOX_OPERATIONS = frozenset(
+    {
+        "modern_messages_received",
+        "modern_messages_sent",
+        "modern_archive_messages_received",
+        "modern_archive_messages_sent",
+    }
+)
+MODERN_CORRESPONDENT_FILTERS = MappingProxyType(
+    {MessageFolder.RECEIVED: "senderId", MessageFolder.SENT: "receiverId"}
+)
+# Filters observed in the web app for the current mailbox only.
+MODERN_MAILBOX_FILTERS = MappingProxyType(
+    {
+        "modern_messages_received": frozenset({"senderId", "unreadOnly"}),
+        "modern_messages_sent": frozenset({"receiverId"}),
+    }
+)
+MODERN_UNREAD_COUNT_FIELDS = (
+    "inbox",
+    "notes",
+    "alerts",
+    "substitutions",
+    "absences",
+    "justifications",
+    "trash",
+)
+MODERN_MAX_UNREAD_COUNT = 1000000
 
 
 def validate_modern_query(operation: str, query: Mapping[str, str]) -> None:
@@ -897,14 +1038,27 @@ def validate_modern_query(operation: str, query: Mapping[str, str]) -> None:
         type(v) is not str for v in query.values()
     ):
         raise LibrusError(ErrorKind.INVALID_INPUT)
-    if operation in {"modern_messages_received", "modern_messages_sent"}:
-        if set(query) != {"page", "limit"} or any(
+    if operation in MODERN_MAILBOX_OPERATIONS:
+        filters = MODERN_MAILBOX_FILTERS.get(operation, frozenset())
+        if not {"page", "limit"} <= set(query) <= {"page", "limit"} | filters or any(
             re.fullmatch(r"[1-9][0-9]{0,3}", query[name]) is None
             for name in ("page", "limit")
         ):
             raise LibrusError(ErrorKind.INVALID_INPUT)
+        folder = (
+            MessageFolder.SENT
+            if operation == "modern_messages_sent"
+            else MessageFolder.RECEIVED
+        )
+        unread = query.get("unreadOnly")
+        if unread not in (None, "1"):
+            raise LibrusError(ErrorKind.INVALID_INPUT)
         modern_mailbox_query(
-            MessageFolder.RECEIVED, int(query["page"]), int(query["limit"])
+            folder,
+            int(query["page"]),
+            int(query["limit"]),
+            correspondent=query.get(MODERN_CORRESPONDENT_FILTERS[folder]),
+            unread_only=unread == "1",
         )
         return
     allowed = [