查询日历与日程

日程查询需要先确定用户和日历，再使用 UTC 时间范围查询日历视图。循环日程可能展开为多次实例，调用方应保留日历 ID 与日程 ID。

调用顺序

1. 调用查询日历列表。
2. 选择目标日历 ID，调用查询时间范围内的日程。
3. 按 nextCursor 读取完整视图。
4. 使用日历 ID 和日程 ID 调用查询日程详情。

Python 示例

import requests

API_BASE = "https://alimail-cn.aliyuncs.com"


def list_events(
    access_token: str,
    mailbox: str,
    calendar_id: str,
    start_time: str,
    end_time: str,
) -> list[dict]:
    headers = {"Authorization": f"Bearer {access_token}"}
    events = []
    cursor = ""
    while True:
        response = requests.get(
            f"{API_BASE}/v2/users/{mailbox}/calendars/{calendar_id}/eventsview",
            headers=headers,
            params={
                "startTime": start_time,
                "endTime": end_time,
                "cursor": cursor,
            },
            timeout=15,
        )
        response.raise_for_status()
        payload = response.json()
        events.extend(payload.get("events", []))
        if not payload.get("hasMore"):
            return events
        cursor = payload["nextCursor"]

时间参数使用 ISO 8601 UTC 格式，例如 2026-07-01T00:00:00Z。展示给用户时再转换到目标时区。

参考：原始示例。