---
title: "List calendar events"
method: GET
path: "/calendar/events"
tags: ["Calendar"]
---

# List calendar events

`GET /calendar/events`

## Request

- Base URL: `https://shipmail.to/api/v1`
- URL: `https://shipmail.to/api/v1/calendar/events`
- Auth: one of:
  - HTTP bearer
  - OAuth 2 (authorization code, authorization URL `https://shipmail.to/api/auth/oauth2/authorize`, token URL `https://shipmail.to/api/auth/oauth2/token`)

List events in a time range for one mailbox's calendar. Set expand=true to return recurring events as individual instances.

## Query parameters

- `mailbox` string, email, required
- `from` string, date-time, required
- `to` string, date-time, required
- `expand` boolean
- `calendar_id` string
- `cursor` string
- `limit` integer

## Headers

- `X-Shipmail-Organization` string

## Response `200`

Paginated list of calendar events.

- object
  - `data` CalendarEvent[], required
    - `object` 'calendar_event', required
    - `id` string, required
    - `revision` string, required: Content revision to pass as expected_revision on a later update.
    - `mailbox` string, email, required: The mailbox (calendar owner) address.
    - `calendar_id` string, nullable, required
    - `uid` string, nullable, required
    - `title` string, nullable, required
    - `invitation_language` 'en' | 'fr' | 'es', required: Language used for Shipmail invitation, update, cancellation, and RSVP interface copy.
    - `description` string, nullable, required
    - `location` string, nullable, required
    - `video_url` string, nullable, required: Video/conference join URL (JSCalendar virtualLocation).
    - `all_day` boolean, required
    - `start` string, required: Timed events: a UTC instant. All-day events: a YYYY-MM-DD date.
    - `end` string, required: Timed events: a UTC instant. All-day events: the exclusive end date.
    - `timezone` string, nullable, required: The event's own IANA time zone. Null for all-day or floating events.
    - `duration` string, nullable, required: ISO 8601 duration, e.g. PT1H.
    - `status` 'confirmed' | 'tentative' | 'cancelled', nullable, required
    - `free_busy_status` 'free' | 'busy', nullable, required
    - `privacy` 'public' | 'private' | 'secret', nullable, required
    - `color` string, nullable, required
    - `recurrence` Recurrence, required
      - `frequency` 'yearly' | 'monthly' | 'weekly' | 'daily' | 'hourly' | 'minutely' | 'secondly', required
      - `interval` integer
      - `count` integer
      - `until` string: Local date-time, e.g. 2026-12-31T00:00:00.
      - `by_day` RecurrenceNDay[]
        - `day` 'mo' | 'tu' | 'we' | 'th' | 'fr' | 'sa' | 'su', required
        - `nth_of_period` integer
    - `recurrence_id` string, nullable, required: Set on an expanded recurrence instance.
    - `reminders` Reminder[], required
      - `minutes_before` integer, required: Minutes before the event start to fire an email reminder.
    - `organizer` CalendarPerson, required
      - `email` string, email, required
      - `name` string, nullable, required
    - `attendees` CalendarAttendee[], required
      - `email` string, email, required
      - `name` string, nullable, required
      - `status` 'needs-action' | 'accepted' | 'declined' | 'tentative', required
    - `created_at` string, date-time, nullable, required
    - `updated_at` string, date-time, nullable, required
  - `pagination` Pagination, required
    - `next_cursor` string, nullable, required: Cursor for the next page. Null if no more results.
    - `has_more` boolean, required: Whether more results exist beyond this page.
    - `limit` integer, required: Number of items per page.

## Other responses

- `404`: Resource not found.
- `422`: Validation failed.
- `429`: Rate limit exceeded.

---

[API](https://skmtc.dev/shipmail/apis/shipmail-api.md) · [All operations](https://skmtc.dev/shipmail/apis/shipmail-api/llms.txt) · [OpenAPI document](https://skmtc.dev/shipmail/apis/shipmail-api/revisions/2c23e59d7e30?raw)