✨(backend) add email invitation endpoint for meeting participants

Implement new endpoint allowing admin/owner to invite participants via email.
Provides explicit way to search users and send meeting invitations with
direct links.

In upcoming commits, frontend will call ResourceAccess endpoint to add
invited people as members if they exist in visio, bypassing waiting room
for a smoother experience.

src/backend/core/api/serializers.py

@@ -223,3 +223,17 @@ class CreationCallbackSerializer(serializers.Serializer):
     def update(self, instance, validated_data):
         """Not implemented as this is a validation-only serializer."""
         raise NotImplementedError("CreationCallbackSerializer is validation-only")
+
+
+class RoomInviteSerializer(serializers.Serializer):
+    """Validate room invite creation data."""
+
+    emails = serializers.ListField(child=serializers.EmailField(), allow_empty=False)
+
+    def create(self, validated_data):
+        """Not implemented as this is a validation-only serializer."""
+        raise NotImplementedError("RoomInviteSerializer is validation-only")
+
+    def update(self, instance, validated_data):
+        """Not implemented as this is a validation-only serializer."""
+        raise NotImplementedError("RoomInviteSerializer is validation-only")

src/backend/core/api/viewsets.py

@@ -41,6 +41,7 @@ from core.recording.worker.factories import (
 from core.recording.worker.mediator import (
     WorkerServiceMediator,
 )
+from core.services.invitation import InvitationService
 from core.services.livekit_events import (
     LiveKitEventsService,
     LiveKitWebhookError,
@@ -497,6 +498,38 @@ class RoomViewSet(
             {"status": "success", "room": room}, status=drf_status.HTTP_200_OK
         )
 
+    @decorators.action(
+        detail=True,
+        methods=["post"],
+        url_path="invite",
+        permission_classes=[
+            permissions.HasPrivilegesOnRoom,
+        ],
+    )
+    def invite(self, request, pk=None):  # pylint: disable=unused-argument
+        """Send email invitations to join a room.
+
+        This API endpoint allows a user with appropriate privileges to send email invitations
+        to one or more recipients, inviting them to join the specified room.
+        """
+
+        room = self.get_object()
+
+        serializer = serializers.RoomInviteSerializer(data=request.data)
+        serializer.is_valid(raise_exception=True)
+
+        emails = serializer.validated_data.get("emails")
+        emails = list(set(emails))
+
+        InvitationService().invite_to_room(
+            room=room, sender=request.user, emails=emails
+        )
+
+        return drf_response.Response(
+            {"status": "success", "message": "invitations sent"},
+            status=drf_status.HTTP_200_OK,
+        )
+
 
 class ResourceAccessListModelMixin:
     """List mixin for resource access API."""

src/backend/core/services/invitation.py

@@ -0,0 +1,59 @@
+"""Invitation Service."""
+
+import smtplib
+from logging import getLogger
+
+from django.conf import settings
+from django.core.mail import send_mail
+from django.template.loader import render_to_string
+from django.utils.translation import get_language, override
+from django.utils.translation import gettext_lazy as _
+
+logger = getLogger(__name__)
+
+
+class InvitationError(Exception):
+    """Exception raised when invitation emails cannot be sent."""
+
+    status_code = 500
+
+
+class InvitationService:
+    """Service for invitations to users."""
+
+    @staticmethod
+    def invite_to_room(room, sender, emails):
+        """Send invitation emails to join a room."""
+
+        language = get_language()
+
+        context = {
+            "brandname": settings.EMAIL_BRAND_NAME,
+            "logo_img": settings.EMAIL_LOGO_IMG,
+            "domain": settings.EMAIL_DOMAIN,
+            "room_url": f"{settings.EMAIL_APP_BASE_URL}/{room.slug}",
+            "room_link": f"{settings.EMAIL_DOMAIN}/{room.slug}",
+            "sender_email": sender.email,
+        }
+
+        with override(language):
+            msg_html = render_to_string("mail/html/invitation.html", context)
+            msg_plain = render_to_string("mail/text/invitation.txt", context)
+            subject = str(
+                _(
+                    f"Video call in progress: {sender.email} is waiting for you to connect"
+                )
+            )  # Force translation
+
+            try:
+                send_mail(
+                    subject,
+                    msg_plain,
+                    settings.EMAIL_FROM,
+                    emails,
+                    html_message=msg_html,
+                    fail_silently=False,
+                )
+            except smtplib.SMTPException as e:
+                logger.error("invitation to %s was not sent: %s", emails, e)
+                raise InvitationError("Could not send invitation") from e

src/backend/core/tests/rooms/test_api_rooms_invite.py

@@ -0,0 +1,295 @@
+"""
+Test rooms API endpoints in the Meet core app: invite.
+"""
+
+# pylint: disable=W0621,W0613
+
+import json
+import random
+from unittest import mock
+
+import pytest
+from rest_framework.test import APIClient
+
+from ...factories import RoomFactory, UserFactory
+from ...services.invitation import InvitationError, InvitationService
+
+pytestmark = pytest.mark.django_db
+
+
+def test_api_rooms_invite_anonymous():
+    """Test anonymous users should not be allowed to invite people to rooms."""
+
+    client = APIClient()
+    room = RoomFactory()
+
+    data = {"emails": ["toto@yopmail.com"]}
+    response = client.post(
+        f"/api/v1.0/rooms/{room.id}/invite/",
+        json.dumps(data),
+        content_type="application/json",
+    )
+
+    assert response.status_code == 401
+
+
+def test_api_rooms_invite_no_access():
+    """Test non-privileged users should not be allowed to invite people to rooms."""
+
+    client = APIClient()
+    room = RoomFactory()
+
+    user = UserFactory()
+    client.force_login(user)
+
+    data = {"emails": ["toto@yopmail.com"]}
+    response = client.post(
+        f"/api/v1.0/rooms/{room.id}/invite/",
+        json.dumps(data),
+        content_type="application/json",
+    )
+
+    assert response.status_code == 403
+    assert response.json() == {
+        "detail": "You must have privileges on room to perform this action.",
+    }
+
+
+def test_api_rooms_invite_member():
+    """Test member users should not be allowed to invite people to rooms."""
+
+    client = APIClient()
+    room = RoomFactory()
+
+    user = UserFactory()
+    client.force_login(user)
+
+    room.accesses.create(user=user, role="member")
+
+    data = {"emails": ["toto@yopmail.com"]}
+    response = client.post(
+        f"/api/v1.0/rooms/{room.id}/invite/",
+        json.dumps(data),
+        content_type="application/json",
+    )
+
+    assert response.status_code == 403
+    assert response.json() == {
+        "detail": "You must have privileges on room to perform this action.",
+    }
+
+
+def test_api_rooms_invite_missing_emails():
+    """Test missing email list should return validation error."""
+
+    client = APIClient()
+    room = RoomFactory()
+    user = UserFactory()
+
+    room.accesses.create(user=user, role=random.choice(["administrator", "owner"]))
+
+    client.force_login(user)
+
+    data = {"foo": []}
+    response = client.post(
+        f"/api/v1.0/rooms/{room.id}/invite/",
+        json.dumps(data),
+        content_type="application/json",
+    )
+
+    assert response.status_code == 400
+    assert response.json() == {
+        "emails": [
+            "This field is required.",
+        ]
+    }
+
+
+def test_api_rooms_invite_empty_emails():
+    """Test empty email list should return validation error."""
+
+    client = APIClient()
+    room = RoomFactory()
+    user = UserFactory()
+
+    room.accesses.create(user=user, role=random.choice(["administrator", "owner"]))
+
+    client.force_login(user)
+
+    data = {"emails": []}
+    response = client.post(
+        f"/api/v1.0/rooms/{room.id}/invite/",
+        json.dumps(data),
+        content_type="application/json",
+    )
+
+    assert response.status_code == 400
+    assert response.json() == {
+        "emails": [
+            "This list may not be empty.",
+        ]
+    }
+
+
+def test_api_rooms_invite_invalid_emails():
+    """Test invalid email addresses should return validation errors."""
+
+    client = APIClient()
+    room = RoomFactory()
+    user = UserFactory()
+
+    room.accesses.create(user=user, role=random.choice(["administrator", "owner"]))
+
+    client.force_login(user)
+
+    data = {"emails": ["abdc", "efg"]}
+
+    response = client.post(
+        f"/api/v1.0/rooms/{room.id}/invite/",
+        json.dumps(data),
+        content_type="application/json",
+    )
+
+    assert response.status_code == 400
+    assert response.json() == {
+        "emails": {
+            "0": ["Enter a valid email address."],
+            "1": ["Enter a valid email address."],
+        }
+    }
+
+
+def test_api_rooms_invite_partially_invalid_emails():
+    """Test partially invalid email addresses should return validation errors."""
+
+    client = APIClient()
+    room = RoomFactory()
+    user = UserFactory()
+
+    room.accesses.create(user=user, role=random.choice(["administrator", "owner"]))
+
+    client.force_login(user)
+
+    data = {"emails": ["fabrice@yopmail.com", "efg"]}
+
+    response = client.post(
+        f"/api/v1.0/rooms/{room.id}/invite/",
+        json.dumps(data),
+        content_type="application/json",
+    )
+
+    assert response.status_code == 400
+    assert response.json() == {
+        "emails": {
+            "1": ["Enter a valid email address."],
+        }
+    }
+
+
+@mock.patch.object(InvitationService, "invite_to_room")
+def test_api_rooms_invite_duplicates(mock_invite_to_room):
+    """Test duplicate emails should be deduplicated before processing."""
+
+    client = APIClient()
+    room = RoomFactory()
+    user = UserFactory()
+
+    room.accesses.create(user=user, role=random.choice(["administrator", "owner"]))
+
+    client.force_login(user)
+
+    data = {"emails": ["toto@yopmail.com", "toto@yopmail.com", "Toto@yopmail.com"]}
+
+    response = client.post(
+        f"/api/v1.0/rooms/{room.id}/invite/",
+        json.dumps(data),
+        content_type="application/json",
+    )
+
+    assert response.status_code == 200
+    mock_invite_to_room.assert_called_once()
+
+    _, kwargs = mock_invite_to_room.call_args
+
+    assert kwargs["room"] == room
+    assert kwargs["sender"] == user
+    assert sorted(kwargs["emails"]) == sorted(["Toto@yopmail.com", "toto@yopmail.com"])
+
+
+@mock.patch.object(InvitationService, "invite_to_room", side_effect=InvitationError())
+def test_api_rooms_invite_error(mock_invite_to_room):
+    """Test invitation service error should return appropriate error response."""
+
+    client = APIClient()
+    room = RoomFactory()
+    user = UserFactory()
+
+    room.accesses.create(user=user, role=random.choice(["administrator", "owner"]))
+
+    client.force_login(user)
+
+    data = {"emails": ["toto@yopmail.com", "toto@yopmail.com"]}
+
+    with pytest.raises(InvitationError) as excinfo:
+        client.post(
+            f"/api/v1.0/rooms/{room.id}/invite/",
+            json.dumps(data),
+            content_type="application/json",
+        )
+
+        mock_invite_to_room.assert_called_once()
+        assert "Could not send invitation" in str(excinfo.value)
+
+
+@mock.patch("core.services.invitation.send_mail")
+def test_api_rooms_invite_success(mock_send_mail, settings):
+    """Test privileged users should successfully send invitation emails."""
+
+    settings.EMAIL_BRAND_NAME = "ACME"
+    settings.EMAIL_LOGO_IMG = "https://acme.com/logo"
+    settings.EMAIL_APP_BASE_URL = "https://acme.com"
+    settings.EMAIL_FROM = "notifications@acme.com"
+    settings.EMAIL_DOMAIN = "acme.com"
+
+    client = APIClient()
+    room = RoomFactory()
+    user = UserFactory()
+
+    room.accesses.create(user=user, role=random.choice(["administrator", "owner"]))
+
+    client.force_login(user)
+
+    data = {"emails": ["fabien@yopmail.com", "gerald@yopmail.com"]}
+
+    response = client.post(
+        f"/api/v1.0/rooms/{room.id}/invite/",
+        json.dumps(data),
+        content_type="application/json",
+    )
+
+    assert response.status_code == 200
+    assert response.json() == {"status": "success", "message": "invitations sent"}
+
+    mock_send_mail.assert_called_once()
+
+    subject, body, sender, recipients = mock_send_mail.call_args[0]
+
+    assert (
+        subject == f"Video call in progress: {user.email} is waiting for you to connect"
+    )
+
+    # Verify email contains expected content
+    required_content = [
+        "ACME",  # Brand name
+        "https://acme.com/logo",  # Logo URL
+        f"https://acme.com/{room.slug}",  # Room url
+        f"acme.com/{room.slug}",  # Room link
+    ]
+
+    for content in required_content:
+        assert content in body
+
+    assert sender == "notifications@acme.com"
+
+    # Verify all owners received the email (order-independent comparison)
+    assert sorted(recipients) == sorted(["fabien@yopmail.com", "gerald@yopmail.com"])