✨(recipients) handle MAX_RECIPIENTS_PER_MESSAGE

Define global env var to configure max recipients allowed per message
Implement frontend restrictions
Add custom_limits on mailbox and maildomain
Add playwright tests

Author: sdemagny

src/backend/core/api/openapi.json

@@ -450,3 +450,33 @@ def has_permission(self, request, view):
         return models.MailboxAccess.objects.filter(
             user=request.user, mailbox=view.kwargs.get("mailbox_id")
         ).exists()
+
+
+class CanManageSettings(permissions.BasePermission):
+    """
+    Permission class that checks if the user has CAN_MANAGE_SETTINGS ability
+    for the given MailDomain or Mailbox object.
+
+    This permission should be used for actions that modify custom_limits and other settings.
+    """
+
+    message = "You do not have permission to manage settings for this resource."
+
+    def has_object_permission(self, request, view, obj):
+        """
+        Check if user has CAN_MANAGE_SETTINGS ability for the object.
+        Works with both MailDomain and Mailbox objects.
+        """
+        if not request.user or not request.user.is_authenticated:
+            return False
+
+        # Get abilities for this object
+        abilities = obj.get_abilities(request.user)
+
+        # Check for the specific ability
+        if isinstance(obj, models.MailDomain):
+            return abilities[enums.MailDomainAbilities.CAN_MANAGE_SETTINGS]
+        if isinstance(obj, models.Mailbox):
+            return abilities[enums.MailboxAbilities.CAN_MANAGE_SETTINGS]
+
+        return False

src/backend/core/api/permissions.py

@@ -4,6 +4,7 @@
 
 import json
 
+from django.conf import settings
 from django.db import transaction
 from django.db.models import Count, Exists, OuterRef, Q
 from django.utils.translation import gettext_lazy as _
@@ -216,10 +217,18 @@ class MailboxSerializer(AbilitiesModelSerializer):
     role = serializers.SerializerMethodField(read_only=True)
     count_unread_messages = serializers.SerializerMethodField(read_only=True)
     count_messages = serializers.SerializerMethodField(read_only=True)
+    max_recipients_per_message = serializers.SerializerMethodField(read_only=True)
 
     class Meta:
         model = models.Mailbox
-        fields = ["id", "email", "role", "count_unread_messages", "count_messages"]
+        fields = [
+            "id",
+            "email",
+            "role",
+            "count_unread_messages",
+            "count_messages",
+            "max_recipients_per_message",
+        ]
 
     def get_email(self, instance):
         """Return the email of the mailbox."""
@@ -280,6 +289,10 @@ def get_abilities(self, instance):
         """Get abilities for the instance."""
         return super().get_abilities(instance)
 
+    def get_max_recipients_per_message(self, instance):
+        """Return the maximum number of recipients per message for the mailbox."""
+        return instance.get_max_recipients_per_message()
+
 
 class MailboxLightSerializer(serializers.ModelSerializer):
     """Serializer for mailbox details in thread access."""
@@ -870,7 +883,14 @@ def get_expected_dns_records(self, instance):
 
     class Meta:
         model = models.MailDomain
-        fields = ["id", "name", "created_at", "updated_at", "expected_dns_records"]
+        fields = [
+            "id",
+            "name",
+            "created_at",
+            "updated_at",
+            "expected_dns_records",
+            "custom_limits",
+        ]
         read_only_fields = fields
 
     @extend_schema_field(
@@ -937,7 +957,7 @@ def validate(self, attrs):
 
 
 class MailDomainAdminWriteSerializer(serializers.ModelSerializer):
-    """Serialize mail domains for creating / editing admin view."""
+    """Serialize mail domains for creating admin view."""
 
     class Meta:
         model = models.MailDomain
@@ -953,6 +973,49 @@ class Meta:
         read_only_fields = ["id", "created_at", "updated_at"]
 
 
+class CustomLimitsUpdateMixin:
+    """Mixin for validating custom_limits field."""
+
+    def validate_custom_limits(self, value):
+        """Validate that custom_limits does not exceed global maximum."""
+        if value and isinstance(value, dict):
+            max_recipients = value.get("max_recipients_per_message")
+            if max_recipients is not None and isinstance(max_recipients, int):
+                if max_recipients > settings.MAX_RECIPIENTS_PER_MESSAGE:
+                    raise serializers.ValidationError(
+                        _(
+                            "The limit cannot exceed the global maximum of %(max)s recipients."
+                        )
+                        % {"max": settings.MAX_RECIPIENTS_PER_MESSAGE}
+                    )
+        return value
+
+
+class MailDomainAdminUpdateSerializer(
+    CustomLimitsUpdateMixin, serializers.ModelSerializer
+):
+    """Serialize mail domains for updating custom_limits only."""
+
+    class Meta:
+        model = models.MailDomain
+        fields = [
+            "id",
+            "custom_limits",
+        ]
+        read_only_fields = ["id"]
+
+
+class MailboxSettingsUpdateSerializer(
+    CustomLimitsUpdateMixin, serializers.ModelSerializer
+):
+    """Serialize mailbox settings (custom_limits) for update operations."""
+
+    class Meta:
+        model = models.Mailbox
+        fields = ["id", "custom_limits"]
+        read_only_fields = ["id"]
+
+
 class MailboxAccessNestedUserSerializer(serializers.ModelSerializer):
     """
     Serialize MailboxAccess for nesting within MailboxAdminSerializer.
@@ -996,6 +1059,7 @@ class Meta:
             "updated_at",
             "can_reset_password",
             "contact",
+            "custom_limits",
         ]
         read_only_fields = [
             "id",
@@ -1152,6 +1216,9 @@ class MailboxAdminCreateSerializer(MailboxAdminSerializer):
     """
     Serialize Mailbox details for create admin endpoint, including users with access and
     metadata.
+
+    Note: custom_limits is excluded from the response as it cannot be set during creation.
+    It can only be modified via the dedicated /settings/ endpoint.
     """
 
     one_time_password = serializers.SerializerMethodField(
@@ -1165,7 +1232,12 @@ def get_one_time_password(self, instance) -> str | None:
 
     class Meta:
         model = models.Mailbox
-        fields = MailboxAdminSerializer.Meta.fields + ["one_time_password"]
+        # Exclude custom_limits from creation response - it can only be set via /settings/
+        fields = [
+            field
+            for field in MailboxAdminSerializer.Meta.fields
+            if field != "custom_limits"
+        ] + ["one_time_password"]
         read_only_fields = fields
 
 

src/backend/core/api/serializers.py

@@ -3,7 +3,10 @@
 from django.conf import settings
 
 import rest_framework as drf
-from drf_spectacular.utils import OpenApiResponse, extend_schema
+from drf_spectacular.utils import (
+    OpenApiResponse,
+    extend_schema,
+)
 from rest_framework.permissions import AllowAny
 
 from core.ai.utils import is_ai_enabled, is_ai_summary_enabled, is_auto_labels_enabled
@@ -82,7 +85,28 @@ class ConfigView(drf.views.APIView):
                         },
                         "MAX_INCOMING_EMAIL_SIZE": {
                             "type": "integer",
-                            "description": "Maximum size in bytes for incoming email (including attachments and body)",
+                            "description": (
+                                "Maximum size in bytes for incoming email "
+                                "(including attachments and body)"
+                            ),
+                            "readOnly": True,
+                        },
+                        "MAX_RECIPIENTS_PER_MESSAGE": {
+                            "type": "integer",
+                            "description": (
+                                "Maximum number of recipients per message "
+                                "(to + cc + bcc) for the entire system. "
+                                "Cannot be exceeded."
+                            ),
+                            "readOnly": True,
+                        },
+                        "MAX_DEFAULT_RECIPIENTS_PER_MESSAGE": {
+                            "type": "integer",
+                            "description": (
+                                "Default maximum number of recipients per message "
+                                "(to + cc + bcc) for a mailbox or maildomain "
+                                "if no custom limit is set."
+                            ),
                             "readOnly": True,
                         },
                     },
@@ -98,6 +122,8 @@ class ConfigView(drf.views.APIView):
                         "MAX_OUTGOING_ATTACHMENT_SIZE",
                         "MAX_OUTGOING_BODY_SIZE",
                         "MAX_INCOMING_EMAIL_SIZE",
+                        "MAX_RECIPIENTS_PER_MESSAGE",
+                        "MAX_DEFAULT_RECIPIENTS_PER_MESSAGE",
                     ],
                 },
             )
@@ -132,6 +158,12 @@ def get(self, request):
         )
         dict_settings["MAX_OUTGOING_BODY_SIZE"] = settings.MAX_OUTGOING_BODY_SIZE
         dict_settings["MAX_INCOMING_EMAIL_SIZE"] = settings.MAX_INCOMING_EMAIL_SIZE
+        dict_settings["MAX_RECIPIENTS_PER_MESSAGE"] = (
+            settings.MAX_RECIPIENTS_PER_MESSAGE
+        )
+        dict_settings["MAX_DEFAULT_RECIPIENTS_PER_MESSAGE"] = (
+            settings.MAX_DEFAULT_RECIPIENTS_PER_MESSAGE
+        )
 
         # Drive service
         if base_url := settings.DRIVE_CONFIG.get("base_url"):

src/backend/core/api/viewsets/config.py

@@ -38,6 +38,7 @@ class AdminMailDomainViewSet(
     mixins.ListModelMixin,
     mixins.RetrieveModelMixin,
     mixins.CreateModelMixin,
+    mixins.UpdateModelMixin,
     viewsets.GenericViewSet,
 ):
     """
@@ -55,12 +56,16 @@ class AdminMailDomainViewSet(
     def get_permissions(self):
         if self.action == "create":
             return [core_permissions.IsSuperUser()]
+        if self.action in ["update", "partial_update"]:
+            return [core_permissions.CanManageSettings()]
         return super().get_permissions()
 
     def get_serializer_class(self):
         """Select serializer based on action."""
         if self.action == "create":
             return core_serializers.MailDomainAdminWriteSerializer
+        if self.action in ["update", "partial_update"]:
+            return core_serializers.MailDomainAdminUpdateSerializer
         return super().get_serializer_class()
 
     def get_queryset(self):
@@ -159,6 +164,21 @@ class AdminMailDomainMailboxViewSet(
     ]
     serializer_class = core_serializers.MailboxAdminSerializer
 
+    def get_serializer_class(self):
+        """Select serializer based on action."""
+        if self.action == "update_settings":
+            return core_serializers.MailboxSettingsUpdateSerializer
+        return super().get_serializer_class()
+
+    def get_permissions(self):
+        """Override permissions for specific actions."""
+        if self.action == "update_settings":
+            # Domain admin + ability to manage settings
+            return [permission() for permission in self.permission_classes] + [
+                core_permissions.CanManageSettings()
+            ]
+        return super().get_permissions()
+
     def get_queryset(self):
         maildomain_pk = self.kwargs.get("maildomain_pk")
         return models.Mailbox.objects.filter(domain_id=maildomain_pk)
@@ -238,6 +258,7 @@ def create(self, request, *args, **kwargs):
                             required=False, allow_blank=True
                         ),
                         "custom_attributes": drf_serializers.JSONField(required=False),
+                        "custom_limits": drf_serializers.JSONField(required=False),
                     },
                 ),
             },
@@ -332,6 +353,38 @@ def reset_password(self, request, *args, **kwargs):
             {"one_time_password": mailbox_password}, status=status.HTTP_200_OK
         )
 
+    @extend_schema(
+        operation_id="maildomains_mailboxes_settings_update",
+        description="Update mailbox settings (custom_limits).",
+        request=core_serializers.MailboxSettingsUpdateSerializer,
+        responses={
+            200: OpenApiResponse(
+                response=core_serializers.MailboxSettingsUpdateSerializer,
+                description="Mailbox settings updated successfully.",
+            ),
+            400: OpenApiResponse(
+                description="Invalid settings data.",
+            ),
+            403: OpenApiResponse(
+                description="User does not have permission to manage settings.",
+            ),
+        },
+    )
+    @action(detail=True, methods=["patch"], url_path="settings")
+    def update_settings(self, request, maildomain_pk=None, pk=None):
+        """
+        Update mailbox settings (custom_limits).
+
+        Only domain administrators can manage mailbox settings.
+        This endpoint is separate from the general mailbox update endpoint
+        to enforce proper permission checks at the viewset level.
+        """
+        mailbox = self.get_object()
+        serializer = self.get_serializer(mailbox, data=request.data, partial=True)
+        serializer.is_valid(raise_exception=True)
+        serializer.save()
+        return Response(serializer.data, status=status.HTTP_200_OK)
+
 
 class AdminMailDomainMessageTemplateViewSet(
     mixins.CreateModelMixin,

src/backend/core/api/viewsets/maildomain.py

@@ -98,6 +98,7 @@ class MailDomainAbilities(models.TextChoices):
 
     CAN_MANAGE_ACCESSES = "manage_accesses", "Can manage accesses"
     CAN_MANAGE_MAILBOXES = "manage_mailboxes", "Can manage mailboxes"
+    CAN_MANAGE_SETTINGS = "manage_settings", "Can manage settings"
 
 
 class MailboxAbilities(models.TextChoices):
@@ -112,6 +113,7 @@ class MailboxAbilities(models.TextChoices):
         "Can manage mailbox message templates",
     )
     CAN_IMPORT_MESSAGES = "import_messages", "Can import messages"
+    CAN_MANAGE_SETTINGS = "manage_settings", "Can manage settings"
 
 
 class MessageTemplateTypeChoices(models.IntegerChoices):