Add recipient list member listing API

Author: alexeygrigorev

mailing/services/api_docs.py

@@ -62,6 +62,7 @@
     "mailing:api_subscribe": "/api/subscriptions/subscribe",
     "mailing:api_unsubscribe": "/api/subscriptions/unsubscribe",
     "mailing:api_recipient_list": "/api/recipient-lists/{list_key}",
+    "mailing:api_recipient_list_members": "/api/recipient-lists/{list_key}/members",
     "mailing:api_recipient_list_member": "/api/recipient-lists/{list_key}/members/{source_object_key}",
     "mailing:api_recipient_list_bulk_upsert": "/api/recipient-lists/{list_key}/members/bulk-upsert",
     "mailing:api_recipient_list_reconcile": "/api/recipient-lists/{list_key}/members/reconcile",
@@ -797,6 +798,7 @@ def endpoint_groups():
             "endpoints": [
                 ("PUT", "/api/recipient-lists/{list_key}", "Create or update a client-scoped recipient list."),
                 ("GET", "/api/recipient-lists/{list_key}", "Get recipient list metadata and counts."),
+                ("GET", "/api/recipient-lists/{list_key}/members", "List recipient-list members for audit."),
                 (
                     "PUT",
                     "/api/recipient-lists/{list_key}/members/{source_object_key}",
@@ -895,6 +897,10 @@ def route_path_map():
             "mailing:api_recipient_list",
             args=["ml-zoomcamp-2026"],
         ),
+        API_DOC_PATHS["mailing:api_recipient_list_members"]: reverse(
+            "mailing:api_recipient_list_members",
+            args=["ml-zoomcamp-2026"],
+        ),
         API_DOC_PATHS["mailing:api_recipient_list_member"]: reverse(
             "mailing:api_recipient_list_member",
             args=["ml-zoomcamp-2026:@e:@homework:homework-1", "homework-submission:42"],
@@ -1354,6 +1360,24 @@ def bearer_responses(success, *, accepted=False):
                 ),
             },
         },
+        "/api/recipient-lists/{list_key}/members": {
+            "get": {
+                "tags": ["Recipient Lists"],
+                "summary": "List recipient list members",
+                "description": "Returns client-scoped list members for audit and drift checks. Active members are returned by default.",
+                "security": [{"BearerAuth": []}],
+                "parameters": [
+                    LIST_KEY_PARAM,
+                    {"name": "audience", "in": "query", "required": True, "schema": {"type": "string"}},
+                    {"name": "client", "in": "query", "required": True, "schema": {"type": "string"}},
+                    {"name": "include_removed", "in": "query", "required": False, "schema": {"type": "boolean", "default": False}},
+                    {"name": "limit", "in": "query", "required": False, "schema": {"type": "integer", "minimum": 1, "maximum": 10000, "default": 1000}},
+                ],
+                "responses": bearer_responses(
+                    json_response("Recipient list members", "#/components/schemas/RecipientListMembersResponse")
+                ),
+            },
+        },
         "/api/recipient-lists/{list_key}/members/{source_object_key}": {
             "put": {
                 "tags": ["Recipient Lists"],
@@ -2323,6 +2347,18 @@ def bearer_responses(success, *, accepted=False):
                 "type": "object",
                 "properties": {"recipient_list": {"$ref": "#/components/schemas/RecipientList"}},
             },
+            "RecipientListMembersResponse": {
+                "type": "object",
+                "properties": {
+                    "recipient_list": {"$ref": "#/components/schemas/RecipientList"},
+                    "members": {
+                        "type": "array",
+                        "items": {"$ref": "#/components/schemas/RecipientListMember"},
+                    },
+                    "count": {"type": "integer"},
+                    "has_more": {"type": "boolean"},
+                },
+            },
             "RecipientListUpsertResponse": {
                 "type": "object",
                 "properties": {

mailing/services/recipient_lists.py

@@ -365,6 +365,51 @@ def get_recipient_list_for_client(list_key, data, authenticated_client):
     return {"recipient_list": recipient_list_payload(recipient_list)}
 
 
+def get_recipient_list_members_for_client(list_key, data, authenticated_client):
+    list_key = validate_path_key(list_key, "list_key")
+    scope = validate_recipient_list_scope(data, authenticated_client)
+    recipient_list = RecipientList.objects.filter(
+        client=scope.client,
+        audience=scope.audience,
+        key=list_key,
+    ).first()
+    if recipient_list is None:
+        raise ApiValidationError({"list_key": "not_found"}, status_code=404)
+
+    include_removed = data.get("include_removed", "false")
+    if include_removed in ("", None, "false", "0", "no"):
+        include_removed = False
+    elif include_removed in ("true", "1", "yes"):
+        include_removed = True
+    else:
+        raise ApiValidationError({"include_removed": "must_be_boolean"})
+
+    limit = data.get("limit", 1000)
+    try:
+        limit = int(limit)
+    except (TypeError, ValueError) as exc:
+        raise ApiValidationError({"limit": "must_be_integer"}) from exc
+    if limit <= 0 or limit > 10000:
+        raise ApiValidationError({"limit": "must_be_between_1_and_10000"})
+
+    queryset = (
+        recipient_list.members.select_related("contact")
+        .order_by("source_object_key", "id")
+    )
+    if not include_removed:
+        queryset = queryset.filter(active=True)
+
+    members = list(queryset[: limit + 1])
+    has_more = len(members) > limit
+    members = members[:limit]
+    return {
+        "recipient_list": recipient_list_payload(recipient_list),
+        "members": [recipient_list_member_payload(member) for member in members],
+        "count": len(members),
+        "has_more": has_more,
+    }
+
+
 def upsert_member(recipient_list, source_object_key, member_data):
     contact, _ = upsert_contact(member_data["email"])
     existing_by_source = RecipientListMember.objects.filter(

mailing/tests/test_client_api.py

@@ -266,6 +266,66 @@ def test_recipient_list_member_upsert_creates_list_and_member_idempotently(clien
     assert get_response.json()["recipient_list"]["member_count"] == 1
 
 
+def test_recipient_list_members_endpoint_lists_scoped_members(client, audience, api_client_record):
+    list_key = "ml-zoomcamp-2026:@e"
+    payload = {
+        "audience": audience.slug,
+        "client": api_client_record.slug,
+        "list": {"name": "ML Zoomcamp 2026 enrolled"},
+        "member": {
+            "email": "learner@example.com",
+            "metadata": {"enrollment_id": 1},
+        },
+    }
+    removed_payload = {
+        **payload,
+        "member": {
+            "email": "removed@example.com",
+            "metadata": {"enrollment_id": 2},
+        },
+    }
+    assert put_json(client, "mailing:api_recipient_list_member", payload, list_key, "enrollment:1").status_code == 200
+    assert put_json(client, "mailing:api_recipient_list_member", removed_payload, list_key, "enrollment:2").status_code == 200
+    assert delete_json(
+        client,
+        "mailing:api_recipient_list_member",
+        {"audience": audience.slug, "client": api_client_record.slug},
+        list_key,
+        "enrollment:2",
+    ).status_code == 200
+
+    active_response = client.get(
+        reverse("mailing:api_recipient_list_members", args=[list_key]),
+        {"audience": audience.slug, "client": api_client_record.slug},
+        **auth_headers(),
+    )
+    all_response = client.get(
+        reverse("mailing:api_recipient_list_members", args=[list_key]),
+        {
+            "audience": audience.slug,
+            "client": api_client_record.slug,
+            "include_removed": "true",
+            "limit": "1",
+        },
+        **auth_headers(),
+    )
+
+    assert active_response.status_code == 200
+    active_body = active_response.json()
+    assert active_body["recipient_list"]["key"] == list_key
+    assert active_body["count"] == 1
+    assert active_body["has_more"] is False
+    assert [member["source_object_key"] for member in active_body["members"]] == ["enrollment:1"]
+    assert active_body["members"][0]["email"] == "learner@example.com"
+    assert active_body["members"][0]["metadata"] == {"enrollment_id": 1}
+
+    assert all_response.status_code == 200
+    all_body = all_response.json()
+    assert all_body["count"] == 1
+    assert all_body["has_more"] is True
+    assert all_body["members"][0]["source_object_key"] == "enrollment:1"
+
+
 def test_recipient_list_reconcile_removes_cascaded_parent_reason(client, audience, api_client_record):
     list_key = "ml-zoomcamp-2026:@e:@homework:homework-1"
     payload = {

mailing/urls.py

@@ -92,6 +92,11 @@
     path("api/subscriptions/subscribe", views.api_subscribe, name="api_subscribe"),
     path("api/subscriptions/unsubscribe", views.api_unsubscribe, name="api_unsubscribe"),
     path("api/recipient-lists/<str:list_key>", views.api_recipient_list, name="api_recipient_list"),
+    path(
+        "api/recipient-lists/<str:list_key>/members",
+        views.api_recipient_list_members,
+        name="api_recipient_list_members",
+    ),
     path(
         "api/recipient-lists/<str:list_key>/members/bulk-upsert",
         views.api_recipient_list_bulk_upsert,

mailing/views.py

@@ -147,6 +147,7 @@
     create_recipient_list_import_job_for_client,
     get_recipient_list_for_client,
     get_recipient_list_import_job_for_client,
+    get_recipient_list_members_for_client,
     reconcile_recipient_list_for_client,
     remove_recipient_list_member_for_client,
     upsert_recipient_list_for_client,
@@ -1345,6 +1346,27 @@ def api_recipient_list_member(request, list_key, source_object_key):
     return JsonResponse(payload, status=200)
 
 
+@csrf_exempt
+def api_recipient_list_members(request, list_key):
+    if request.method != "GET":
+        return method_not_allowed_response(["GET"])
+
+    client, error_response = authenticate_api_request(request)
+    if error_response:
+        return error_response
+
+    try:
+        payload = get_recipient_list_members_for_client(
+            list_key,
+            request.GET,
+            client,
+        )
+    except ApiValidationError as exc:
+        return validation_error_response(exc)
+
+    return JsonResponse(payload, status=200)
+
+
 @csrf_exempt
 def api_recipient_list_bulk_upsert(request, list_key):
     if request.method != "POST":