List events in a time range

GET/api/v1/mailbox/calendars/{calendar}/events
Requires amailbox token— it acts as one mailbox holder, not as the organization.

Events overlapping start–end (ISO 8601, at most 400 days apart). Repeating events come back once per occurrence in the range.

Errors

Status When
401 No token, or the session expired or was signed out. Sign in again with POST /mailbox-auth/login.
403 The account has a temporary password: until POST /security/password succeeds, every other call answers this with error_code: password_change_required.
400 end must be after start, a range over 400 days, or an invalid time zone.
404 No calendar by that name.

Parameters

NameInTypeDescription
calendarrequiredpathstring
startrequiredquerystringISO 8601, inclusive
endrequiredquerystringISO 8601, exclusive

Request

GET/api/v1/mailbox/calendars/{calendar}/events
curl -X GET 'https://courier.mailyte.com/api/v1/mailbox/calendars/01JBT8XQ2M9WYC3K4F6R7S8T9V/events' \
  -H 'Authorization: Bearer MAILBOX_TOKEN'

Response

Successful Response

  • dataarray<object>
    • idstring

      The event's id within its calendar; use it in the event URLs.

    • etagstring

      Send it back as etag when you update or delete, so a change made elsewhere is not overwritten.

    • calendarstring
    • uidstring
    • summarystring or null
    • descriptionstring or null
    • locationstring or null
    • statusstring or null
    • startstring

      ISO 8601.

    • endstring or null
    • timezonestring or null
    • all_dayboolean
    • recurringboolean
    • rrulestring or null
    • sequenceinteger
    • organizerobject
      • emailstring
      • namestring or null
    • attendeesarray<object>
      • emailstring
      • namestring or null
      • statusstring
      • rolestring
      • rsvpboolean
      • schedule_statusstring or null
    • alarmsinteger
    • remindersarray<integer>

      Minutes before the start.

200application/json
{
  "type": "success",
  "msg": "Events retrieved successfully",
  "data": [
    {
      "id": "8f14e45f.ics",
      "etag": "\"a1b2c3\"",
      "calendar": "default",
      "uid": "8f14e45f@yourdomain.com",
      "summary": "Quarterly review",
      "description": "Q3 numbers and the plan for Q4.",
      "location": "Board room",
      "status": "CONFIRMED",
      "start": "2026-10-14T10:00:00+01:00",
      "end": "2026-10-14T11:00:00+01:00",
      "timezone": "Africa/Lagos",
      "all_day": false,
      "recurring": false,
      "rrule": null,
      "sequence": 0,
      "organizer": {
        "email": "ada@yourdomain.com",
        "name": "Ada Obi"
      },
      "attendees": [
        {
          "email": "tunde@example.com",
          "name": "Tunde Bello",
          "status": "NEEDS-ACTION",
          "role": "REQ-PARTICIPANT",
          "rsvp": true,
          "schedule_status": null
        }
      ],
      "alarms": 1,
      "reminders": [
        15
      ]
    }
  ]
}

Returned inside the standard envelope.

Errors

StatusWhen
400`end must be after start`, a range over 400 days, or an invalid time zone.
401No token, or the session expired or was signed out. Sign in again with `POST /mailbox-auth/login`.
403The account has a temporary password: until `POST /security/password` succeeds, every other call answers this with `error_code: password_change_required`.
404No calendar by that name.
422Validation Error

Every status, with what causes it and what to do, is on the error reference.