Graph: Improve Event TimeZone Handling

[tmcqueen-materials]

Thank you for the great tool, and for working proactively to add Microsoft Graph (#404) support prior to EWS discontinuation.

In testing out the CalDav support (at 16b84b5), I observe that the user timezone (as set in mailbox settings on the server, or manually with davmail.timezoneId=XXX) does not necessarily match the timezone of the datetimes returned by Graph for event objects. For example, the user timezone might be Eastern Standard Time but all datetimes returned by graph have timezone of UTC.

This causes two problems.

Problem 1: Events end up at incorrect times because the timezone is changed to the user timezone value, but the time itself is left in UTC. What happens is convertDateTimeTimeZoneToVProperty takes the Graph datetime and converts it to ICS formatting style, and (correctly!) keeps the Graph-provided timezone as TZID. But then fixVCalendar blindly replaces the TZID with the user timezone, without doing the time conversion. Simply changing the VCalendar timezone to be that of the start date, instead of the user timezone is not an appropriate fix to the problem because of problem 2...

Problem 2: Even when using the Graph-reported timezone for DSTART, events with recurrences that cross daylight savings time transitions may end up with incorrect times on one side or the other. It appears to be the case that Microsoft Graph (at least on my tenant) always returns event times in UTC. The start times are correct (i.e. the specified UTC time is in fact the start time of the event on that date), but for recurring events, using the timezone UTC in the ICS file then fails to capture the shift in time across the daylight savings time transition.

For example, a recurring event created in Microsoft O365 online to occur at 2:30 PM every Thursday starting on August 1, 2025 in America/New_York will, through Microsoft online, correctly appear at 2:30 PM (in user timezone) in August and in December. Microsoft Graph returns the start time of this event series in UTC, but when the ICS file is then returned with the use of UTC, the fact that daylight savings time should be applied is lost, and so the ICS file implies a 2:30 PM start in August but a 1:30 PM start in December.

I am not entirely sure what the correct solution is here, but what is working for me is a two-fold change:

1. Modify convertDateTimeTimeZoneToVProperty to convert from the Graph-provided timezone to the user timezone (whether that is the timezone from the server or set manually in davmail). Viz:

    private VProperty convertDateTimeTimeZoneToVproperty(String vPropertyName, JSONObject jsonDateTimeTimeZone) throws DavMailException {
        if (jsonDateTimeTimeZone != null) {
            String timeZone = jsonDateTimeTimeZone.optString("timeZone");
            String dateTime = convertDateFromExchange(jsonDateTimeTimeZone.optString("dateTime"));
            SimpleDateFormat parser = new SimpleDateFormat("yyyyMMdd'T'HHmmss");
            SimpleDateFormat formatter = new SimpleDateFormat("yyyyMMdd'T'HHmmss");
            parser.setTimeZone(TimeZone.getTimeZone(convertTimezoneFromExchange(timeZone)));
            formatter.setTimeZone(TimeZone.getTimeZone(convertTimezoneFromExchange(getVTimezone().getPropertyValue("TZID"))));
            try {
                dateTime = formatter.format(parser.parse(Character.isDigit(dateTime.charAt(dateTime.length()-1)) ? (dateTime) : (dateTime.substring(0, dateTime.length()-1))));
                timeZone = getVTimezone().getPropertyValue("TZID");
            } catch (ParseException e) {
                LOGGER.warn("Unable to convert to user timezone: " + dateTime + ", " + timeZone + ", " + getVTimezone().getPropertyValue("TZID"));
            }
            VProperty vProperty = new VProperty(vPropertyName, dateTime);
            vProperty.addParam("TZID", timeZone);
            return vProperty;
        }
        return new VProperty(vPropertyName, null);
    }

2. Modify fixVCalendar to not blindly clobber TZID, but instead do the Exchange->Universal name conversion individually each time. This is probably just defense in depth given the first change, but I see no harm to correctly doing this, always, as the ICS specification allows different VTIMEZONE and TZIDs within a single ICS file.

Let me know if more information is needed to track this down. It is quite possible there are similar issues in the inverse (upload) direction, and/or for tasks/todo, but I have not checked.

[tmcqueen-materials]

I opened a couple of pull requests implementing the solutions above.

Comparison with and without #476 proves useful in highlighting there are at least two code paths where the timezone conversion on the davmail side (appears) to be incomplete. One is in the endDate of RRULEs (user timezone is "Eastern Standard Time":

-RRULE:FREQ=WEEKLY;UNTIL=20260519T190000Z;INTERVAL=1;BYDAY=TU;WKST=SU [when server returns in user timezone]
+RRULE:FREQ=WEEKLY;UNTIL=20260519T230000Z;INTERVAL=1;BYDAY=TU;WKST=SU [when server returns in UTC]

And the other is in RECURRENCE-ID:

-RECURRENCE-ID;TZID=Eastern Standard Time:20250616T120000 [when server returns in user timezone]
+RECURRENCE-ID;TZID=Eastern Standard Time:20250616T160000 [when server returns in UTC]

In a sampling of almost 10,000 diverse events from multiple users across more than a decade, the returned ICS files are otherwise identical with and without #476 (when #477, #478, #479, #480 are all included in both cases). I have not delved into the code to learn what needs updating to handle these.

[tmcqueen-materials]

Added a third PR that addresses the timezone issues with recurrences. The differences come because of some ugliness in how Microsoft Graph defines originalStart and originalStartTimeZone combined with the fact that Microsoft Graph returns timezones with each datetime object which may or may not match timezones elsewhere. Seems to be working for me, but as noted in the PR, parts of it need more testing. And I don't claim to know the code well enough to know if this is complete.

[mguessan]

Tried a different approach based on test results with DavMail set to UTC and client to a different timezone:

We want to restore original timezone on recurring events to preserve event start and end across DST.
=> when retrieving event, fetch originalTimeZone and convert DTSTART/DTEND accordingly, also ensure VCALENDAR contains VTIMEZONE for TZID

originalStart is always in UTC => adjust getRecurrenceId to convert recurrence id to original timezone.

I didn't merge the separate timezone per attribute as this would add more complexity (need multiple VTIMEZONE objects on event), assumption is Exchange converts event to MAPI properties on creation and one timezone should be enough. Will fix if this assumption is proven wrong.

[tmcqueen-materials]

@mguessan : Thanks! I put this in #481 just now, but also putting here: even though the graph doc say originalStart is always UTC ("but in an ISO 8601 format"), in my testing it is always returned in an ISO 8601 timezone which may or may not be UTC (i.e. "Z" or "+00:00"). That is why I set these to actually parse originalStart as an ISO8601 time -- because that is clearly the format it is. I took the UTC part of the comment as implying that when stuffed in recurrenceId it should always be UTC (and end with a Z) even with a TZID. But again, I'm not an expert on these kinds of details. What I think is most important is the recurrence-ID to be the same independent of the user timezoneid setting. Thanks!!

(I confirmed that on 4092 if my timezoneid is not UTC, then I see a bunch of originalStart is not UTC error messages).

[tmcqueen-materials]

@mguessan : 4092 definitely doesn't work for me. In particular, any event with a MS custom timezone fails:

2026-05-09T07:40:27.845667506-04:00 stdout F java.io.IOException: Can't find resource for bundle java.util.PropertyResourceBundle, key tzone://Microsoft/Custom
2026-05-09T07:40:27.845667506-04:00 stdout F    at davmail.exchange.graph.GraphExchangeSession$Event.getEventContent(Unknown Source)
2026-05-09T07:40:27.845667506-04:00 stdout F    at davmail.exchange.ExchangeSession$Event.getBody(Unknown Source)
2026-05-09T07:40:27.845667506-04:00 stdout F    at davmail.caldav.CaldavConnection.appendItemResponse(Unknown Source)
2026-05-09T07:40:27.845667506-04:00 stdout F    at davmail.caldav.CaldavConnection.reportItems(Unknown Source)
2026-05-09T07:40:27.845667506-04:00 stdout F    at davmail.caldav.CaldavConnection.handleFolderOrItem(Unknown Source)
2026-05-09T07:40:27.845667506-04:00 stdout F    at davmail.caldav.CaldavConnection.handleRequest(Unknown Source)
2026-05-09T07:40:27.845667506-04:00 stdout F    at davmail.caldav.CaldavConnection.run(Unknown Source)
2026-05-09T07:40:27.845667506-04:00 stdout F Caused by: java.util.MissingResourceException: Can't find resource for bundle java.util.PropertyResourceBundle, key tzone://Microsoft/Custom
2026-05-09T07:40:27.845667506-04:00 stdout F    at java.base/java.util.ResourceBundle.getObject(ResourceBundle.java:567)
2026-05-09T07:40:27.845667506-04:00 stdout F    at java.base/java.util.ResourceBundle.getString(ResourceBundle.java:523)
2026-05-09T07:40:27.845667506-04:00 stdout F    at davmail.exchange.graph.GraphExchangeSession.getVTimezone(Unknown Source)
2026-05-09T07:40:27.845667506-04:00 stdout F    ... 7 more

This will happen if someone else uses a custom timezone and invites you to a meeting.

[mguessan]

@tmcqueen-materials MRE should be fixed, working on originalStart parsing, please reopen if still broken