Skip to navigation
API ReferenceInboxesCalendar

Get Agenda

Beta

Lists every date on the calendar in a time window, ordered by start time: one-off events, and recurring events expanded into their individual dates, with cancelled dates left out. Use it to answer “what is on the calendar”.

The window defaults to now through 90 days from now and can be at most 366 days. Items omit description, metadata and attendees; get an event by ID for the full object. Dates of recurring events appear only up to about 90 days from now; use List Event Instances for a recurring event’s later dates. While a recurring event’s dates are being regenerated after a schedule change, which takes a few seconds, the agenda can briefly leave out some of them; dates that have already started or ended stay as they ran.

The agenda is read in the region that serves the request, so it 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.

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