fix: accept_invite() falls back to client username when calendar-user-address-set is unavailable

When the server does not expose the calendar-user-address-set property
(RFC6638 §2.4.1), accept_invite() (and decline_invite(),
tentatively_accept_invite()) now fall back to the client username as
the attendee email address. A NotFoundError with a descriptive message
is raised when the username is also not an email address.

Fixes #399

Author: tobixen

CHANGELOG.md

@@ -21,6 +21,7 @@ This project should adhere to [Semantic Versioning](https://semver.org/spec/v2.0
 * `Calendar.get_supported_components()`
   * raised `KeyError` when the server did not include the `supported-calendar-component-set` property in its response.  RFC 4791 section 5.2.3 states this property is optional and that its absence means all component types are accepted; the method now returns the RFC default `["VEVENT", "VTODO", "VJOURNAL"]` in that case, trimmed by any known server limitations from the compatibility hints (e.g. if `save-load.todo` is `unsupported`, `VTODO` is excluded).  Fixes https://github.com/python-caldav/caldav/issues/653
   * async path returned an unawaited coroutine instead of the actual result.
+* `accept_invite()` (and `decline_invite()`, `tentatively_accept_invite()`) now fall back to the client username as the attendee email address when the server does not expose the `calendar-user-address-set` property (RFC6638 §2.4.1).  A `NotFoundError` with a descriptive message is raised when the username is also not an email address.  Fixes https://github.com/python-caldav/caldav/issues/399
 
 ## [3.1.0] - 2026-03-19
 

caldav/calendarobjectresource.py

@@ -1055,7 +1055,22 @@ def change_attendee_status(self, attendee: Any | None = None, **kwargs) -> None:
         cnt = 0
 
         if isinstance(attendee, Principal):
-            attendee_emails = attendee.calendar_user_address_set()
+            try:
+                attendee_emails = attendee.calendar_user_address_set()
+            except error.NotFoundError:
+                ## Server does not expose calendar-user-address-set (RFC6638 §2.4.1).
+                ## Fall back to client.username if it looks like an email address.
+                ## See https://github.com/python-caldav/caldav/issues/399
+                username = getattr(self.client, "username", None)
+                if username and "@" in str(username):
+                    attendee_emails = ["mailto:" + username]
+                else:
+                    raise error.NotFoundError(
+                        "Server does not provide the calendar-user-address-set property "
+                        "(RFC6638 §2.4.1) and the client username is not an email address. "
+                        "Cannot determine which attendee to update. "
+                        "Pass the attendee email address explicitly to change_attendee_status()."
+                    ) from None
             for addr in attendee_emails:
                 try:
                     self.change_attendee_status(addr, **kwargs)

tests/test_caldav.py

@@ -835,6 +835,79 @@ def testInviteAndRespond(self):
         assert new_organizer_inbox_items[0].is_invite_reply()
         new_organizer_inbox_items[0].delete()
 
+    def testAcceptInviteUsernameEmailFallback(self):
+        """accept_invite() works when the invite was built with username-as-email (issue #399).
+
+        The invite is constructed using the attendee's login username directly
+        instead of get_vcal_address(), mirroring what a client must do when the
+        server does not expose calendar-user-address-set.
+
+        On servers that expose calendar-user-address-set the normal code path
+        runs inside accept_invite(); on servers that do not, the username-email
+        fallback introduced by the fix kicks in.  Both paths produce the same
+        observable outcome (PARTSTAT updated, invite accepted), so this test is
+        valid regardless of whether calendar-user-address-set is available.
+
+        Only runs when:
+        - two principals are available
+        - the server delivers iTIP requests to the inbox
+        - the attendee's login username is an email address
+        """
+        if len(self.principals) < 2:
+            pytest.skip("need 2 principals to do the invite and respond test")
+
+        attendee_client = self.clients[1]
+        if not attendee_client.features.is_supported("scheduling.mailbox.inbox-delivery"):
+            pytest.skip("server does not deliver iTIP requests to the inbox")
+        attendee_username = getattr(attendee_client, "username", None)
+        if not attendee_username or "@" not in str(attendee_username):
+            pytest.skip(
+                "Attendee username %r is not an email address; "
+                "cannot build a matching ATTENDEE line" % attendee_username
+            )
+        attendee_email = "mailto:" + attendee_username
+
+        inbox_items = set(x.url for x in self.principals[0].schedule_inbox().get_items())
+        inbox_items.update(x.url for x in self.principals[1].schedule_inbox().get_items())
+
+        organizers_calendar = self._getCalendar(0)
+        attendee_calendar = self._getCalendar(1)
+        ## Build the invite using the attendee's email directly, since
+        ## get_vcal_address() would also fail without calendar-user-address-set.
+        ## Use a fresh UUID so Zimbra (and other servers) don't treat this as a
+        ## duplicate of the event sent by testInviteAndRespond.  Both tests use
+        ## the module-level `sched` which has the same UID for the whole test
+        ## session, so reusing it causes Zimbra to silently skip inbox delivery.
+        fresh_sched = sched_template % (
+            str(uuid.uuid4()),
+            "%2i%2i%2i" % (random.randint(0, 23), random.randint(0, 59), random.randint(0, 59)),
+            random.randint(1, 28),
+            "%2i%2i%2i" % (random.randint(0, 23), random.randint(0, 59), random.randint(0, 59)),
+        )
+        saved_event = organizers_calendar.save_with_invites(
+            fresh_sched, [self.principals[0], attendee_email]
+        )
+        self._auto_scheduled_event_uids.append(saved_event.id)
+
+        new_attendee_inbox_items = []
+        for _ in range(30):
+            new_attendee_inbox_items = [
+                item
+                for item in self.principals[1].schedule_inbox().get_items()
+                if item.url not in inbox_items
+            ]
+            if new_attendee_inbox_items:
+                break
+            time.sleep(1)
+
+        assert len(new_attendee_inbox_items) == 1, (
+            "expected exactly one new inbox item for attendee"
+        )
+        assert new_attendee_inbox_items[0].is_invite_request()
+
+        ## accept_invite() must work via the username-email fallback.
+        new_attendee_inbox_items[0].accept_invite(calendar=attendee_calendar)
+
     ## TODO.  Invite two principals, let both of them load the
     ## invitation, and then let them respond in order.  Lacks both
     ## tests and the implementation also apparently doesn't work as
@@ -1190,6 +1263,53 @@ def testSchedulingInfo(self):
         calendar_user_address_set = self.principal.calendar_user_address_set()
         me_a_participant = self.principal.get_vcal_address()
 
+    def testIssue399ChangeAttendeeStatusUsernameEmailFallback(self):
+        """change_attendee_status() works when the attendee is identified
+        by the client username rather than calendar_user_address_set() (issue #399).
+
+        On servers that expose calendar-user-address-set the normal path runs;
+        on servers that do not, the username-email fallback introduced by the
+        fix kicks in.  Either way the PARTSTAT update must succeed.
+        Only skipped when the login username is not an email address.
+        """
+        self.skip_unless_support("scheduling")
+        username = getattr(self.caldav, "username", None)
+        if not username or "@" not in str(username):
+            pytest.skip(
+                "Client username %r is not an email address; "
+                "cannot build a matching ATTENDEE line" % username
+            )
+        my_email = "mailto:" + username
+
+        invite_data = """\
+BEGIN:VCALENDAR
+VERSION:2.0
+PRODID:-//Test//Test//EN
+METHOD:REQUEST
+BEGIN:VEVENT
+UID:test-issue-399-%s@test.example
+DTSTAMP:%s
+DTSTART:%s
+DTEND:%s
+SUMMARY:Test invite for issue 399
+ORGANIZER:mailto:organizer@test.example
+ATTENDEE;PARTSTAT=NEEDS-ACTION:%s
+END:VEVENT
+END:VCALENDAR
+""" % (
+            uuid.uuid4(),
+            datetime.now(timezone.utc).strftime("%Y%m%dT%H%M%SZ"),
+            (datetime.now(timezone.utc) + timedelta(days=10)).strftime("%Y%m%dT%H%M%SZ"),
+            (datetime.now(timezone.utc) + timedelta(days=10, hours=1)).strftime("%Y%m%dT%H%M%SZ"),
+            my_email,
+        )
+
+        ev = Event(client=self.caldav, data=invite_data)
+        ev.change_attendee_status(partstat="ACCEPTED")
+
+        attendee = ev.icalendar_component["attendee"]
+        assert attendee.params.get("PARTSTAT") == "ACCEPTED"
+
     def testSchedulingMailboxes(self):
         self.skip_unless_support("scheduling.mailbox")
         inbox = self.principal.schedule_inbox()

tests/test_caldav_unit.py

@@ -2866,3 +2866,60 @@ def test_add_organizer_no_arg_no_client_raises(self):
         ev.client = None
         with pytest.raises(ValueError):
             ev.add_organizer()
+
+
+class TestChangeAttendeeStatusFallback:
+    """Unit tests for change_attendee_status() fallback when calendar_user_address_set() is unavailable.
+
+    Covers issue https://github.com/python-caldav/caldav/issues/399: accept_invite() fails on servers
+    that do not expose the calendar-user-address-set property (RFC6638 §2.4.1).
+    """
+
+    _invite = """\
+BEGIN:VCALENDAR
+VERSION:2.0
+PRODID:-//Test//Test//EN
+METHOD:REQUEST
+BEGIN:VEVENT
+UID:test-invite-399@example.com
+DTSTAMP:20240101T000000Z
+DTSTART:20240601T100000Z
+DTEND:20240601T110000Z
+SUMMARY:Test invite
+ORGANIZER:mailto:organizer@example.com
+ATTENDEE;PARTSTAT=NEEDS-ACTION:mailto:attendee@example.com
+END:VEVENT
+END:VCALENDAR
+"""
+
+    def _make_event_with_mock_client(self, username):
+        from caldav.collection import Principal
+        from caldav.lib import error as caldav_error
+
+        ev = Event(data=self._invite)
+        mock_client = mock.MagicMock()
+        mock_client.username = username
+        mock_principal = mock.MagicMock(spec=Principal)
+        mock_principal.calendar_user_address_set.side_effect = caldav_error.NotFoundError(
+            "calendar-user-address-set not supported"
+        )
+        mock_client.principal.return_value = mock_principal
+        ev.client = mock_client
+        return ev
+
+    def test_change_attendee_status_falls_back_to_email_username(self):
+        """When calendar_user_address_set() raises NotFoundError and username is an email,
+        change_attendee_status() should use the username as the attendee address."""
+        ev = self._make_event_with_mock_client("attendee@example.com")
+        ev.change_attendee_status(partstat="ACCEPTED")
+        attendee = ev.icalendar_component["attendee"]
+        assert attendee.params.get("PARTSTAT") == "ACCEPTED"
+
+    def test_change_attendee_status_raises_when_username_not_email(self):
+        """When calendar_user_address_set() raises NotFoundError and username is not an email,
+        change_attendee_status() should re-raise NotFoundError with a descriptive message."""
+        from caldav.lib import error as caldav_error
+
+        ev = self._make_event_with_mock_client("just_a_username")
+        with pytest.raises(caldav_error.NotFoundError):
+            ev.change_attendee_status(partstat="ACCEPTED")