Skip to navigation
API ReferenceInboxesCalendar

List Event Instances

Beta

Lists the dates of one recurring event in a time window, in start order, with each date’s edits applied. Dates are computed from the rule, so this works for any window up to 366 days, including dates far in the future. Cancelled dates are left out.

The window defaults to now through 90 days from now. Items omit description, metadata and attendees; get a date by its ID for the full object. Like other reads, the list can trail a change made moments earlier by a few seconds; pass consistency=primary to read your own change right away. Requires the calendar_event_read permission.

Calendar is in private beta in US production (api.agentmail.to). It is unavailable in EU production (api.agentmail.eu). Organizations without access receive a 403.

Authentication

AuthorizationBearer

Bearer authentication of the form Bearer <token>, where token is your auth token.

Path parameters

inbox_idstringRequired
The ID of the inbox.
event_idstringRequired
UUID of the recurring event.

Query parameters

consistencyenumOptional

Read consistency. eventual (default) reads from the region that serves your request and may lag a write made moments earlier by up to a few seconds. primary reads from the primary region and always reflects every completed write.

Allowed values:
afterdatetimeOptional

Start of the window, as a UTC timestamp ending in Z (an offset such as -04:00 is rejected). Defaults to now. The window between after and before can be at most 366 days.

beforedatetimeOptional

End of the window, as a UTC timestamp ending in Z (an offset such as -04:00 is rejected). Defaults to 90 days after after. The window between after and before can be at most 366 days.

include_overlappingbooleanOptional

When true (default), include events that started before after but are still running at after. When false, include only events that start inside the window.

limitintegerOptional
Maximum number of events to return, from 1 to 100. Defaults to 50.
page_tokenstringOptional
Page token for pagination.

Response

This endpoint returns an object.
countinteger
Number of items returned.
limitinteger
Limit of number of items returned.
eventslist of objects

On List Events, ordered by updated_at descending. On Get Agenda and List Event Instances, ordered by start_at ascending.

next_page_tokenstringOptional
Page token for pagination.

Errors

400
Validation Error
403
Forbidden Error
404
Not Found Error
409
Conflict Error