Query Calendars and Events

To query events, you must first identify the user and calendar, then use a UTC time range to query the calendar view. Recurring events may be expanded into multiple instances; the caller should retain the calendar ID and event ID.

Call Sequence

1. Call List Calendars.
2. Select the target calendar ID, then call Query Events in Time Range.
3. Read the full view via nextCursor.
4. Use the calendar ID and event ID to call Query Event Details.

Python Example

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"]

Time parameters use ISO 8601 UTC format, e.g., 2026-07-01T00:00:00Z. Convert to the target time zone when displaying to users.

Reference: Original Example.