> For clean Markdown content of this page, append .md to this URL. For the complete documentation index, see https://docs.agentmail.to/llms.txt. # Get Agenda GET https://api.agentmail.to/v0/inboxes/{inbox_id}/calendar/agenda 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`. Reference: https://docs.agentmail.to/api-reference/inboxes/calendar/get-agenda ## Authentication - `Authorization` header (bearer token, required) — Bearer authentication of the form `Bearer `, where token is your auth token. ## Servers - `https://api.agentmail.to` (prod, default) - `https://x402.api.agentmail.to` (prod-x402) - `https://mpp.api.agentmail.to` (prod-mpp) - `https://api.agentmail.eu` (eu-prod) ## Request ### Path parameters - `inbox_id` (string, required) — The ID of the inbox. ### Query parameters - `consistency` (enum, optional) — 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: `eventual`, `primary` - `after` (datetime, optional) — 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. - `before` (datetime, optional) — 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_overlapping` (boolean, optional) — 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. - `limit` (integer, optional) — Maximum number of events to return, from 1 to 100. Defaults to 50. - `page_token` (string, optional) — Page token for pagination. ## Response ### 200 - `count` (integer, required) — Number of items returned. - `limit` (integer, required) — Limit of number of items returned. - `events` (list of CalendarEvent, required) — On List Events, ordered by `updated_at` descending. On Get Agenda and List Event Instances, ordered by `start_at` ascending. - `next_page_token` (string, optional) — Page token for pagination. ## Errors ### 400 Validation Error - `name` (string, required) — Name of error. - `errors` (any, required) — Validation errors. Each entry has a path and a message identifying the invalid field. - `code` (string, optional) — Stable, machine-readable error code in snake_case (for example, not_found or missing_permission). Branch on this rather than the message text. - `message` (string, optional) — Error message. - `fix` (string, optional) — The concrete next action that resolves the error. - `docs` (string, optional) — Link to the error reference entry for this code. ### 403 Forbidden Error The organization does not have calendar access (calendar is in private beta), or the API key lacks the required calendar permission. - `name` (string, required) — Name of error. - `message` (string, required) — Error message. - `code` (string, optional) — Stable, machine-readable error code in snake_case (for example, not_found or missing_permission). Branch on this rather than the message text. - `fix` (string, optional) — The concrete next action that resolves the error. - `docs` (string, optional) — Link to the error reference entry for this code. ### 404 Not Found Error - `name` (string, required) — Name of error. - `message` (string, required) — Error message. - `code` (string, optional) — Stable, machine-readable error code in snake_case (for example, not_found or missing_permission). Branch on this rather than the message text. - `fix` (string, optional) — The concrete next action that resolves the error. - `docs` (string, optional) — Link to the error reference entry for this code. ## Types ### CalendarEvent A calendar event. The same shape is used by every response, list item and webhook. `kind` says whether it is a one-off event, the definition of a recurring series, or one date of a series. - `event_id` (string, required) — ID of a calendar event. A one-off or recurring event is addressed by its UUID. One date of a recurring event is addressed by a dated ID, `_`: `_t20261015T090000` for a timed date (the original wall-clock start in the event's time zone) or `_d20261015` for an all-day date. Dated IDs are stable: moving a date keeps its original ID. - `kind` (enum, required) — What the event object represents. - `single`: a one-off event, addressed by its UUID. - `series`: the definition of a recurring event, addressed by its UUID. It carries `recurrence`; `start` and `end` describe its first date. - `instance`: one date of a recurring event, addressed by its dated ID. It carries `series_id`, `original_start` and `is_exception`. - Allowed values: `single`, `series`, `instance` - `title` (string, required) — Title of the event. - `status` (enum, required) — Status of the event. A `cancelled` event or date stays readable but sends no `calendar.event.starting` or `calendar.event.ending` webhooks (cancelling a date that is already running still sends its `calendar.event.ending`). A date cancelled by deleting its dated ID is removed from the series instead, so reading it can return `404` or `410`. - Allowed values: `confirmed`, `tentative`, `cancelled` - `all_day` (boolean, required) — Whether this is an all-day event. - `start` (string, required) — Local start time in `timezone`. For all-day events, the first day. - `end` (string, required) — Local end time in `timezone`. For all-day events, the last day (inclusive). - `timezone` (string, required) — Canonical IANA time zone name, for example `America/New_York`, `Europe/London` or `UTC`. Abbreviations such as `PST`, Windows names such as `Pacific Standard Time`, and spellings that differ from the canonical name are rejected. - `duration_mode` (enum, required) — How the event's length is kept when a date crosses a daylight-saving change. - `exact`: the event lasts the same elapsed time. Default for one-off timed events. - `nominal`: the event keeps its wall-clock end time (a 09:00 to 10:00 meeting stays 09:00 to 10:00 local time). Default for recurring timed events. All-day events are always `nominal`. - Allowed values: `nominal`, `exact` - `duration_value` (integer, required) — Length of the event, in milliseconds for timed events and in days for all-day events. - `start_at` (datetime, required) — Start as a UTC instant. This is when `calendar.event.starting` is due. - `end_at` (datetime, required) — End as a UTC instant. This is when `calendar.event.ending` is due. - `attendee_count` (integer, required) — Number of attendees. - `uid` (string, required) — iCalendar UID of the event. Invitations about this event carry the same UID. - `sequence` (integer, required) — iCalendar SEQUENCE number. It increases when a change to a one-off or series event affects what attendees see (time, status, title, description, location, recurrence or attendees). A change to a dated event increases it only when the change is sent with `send_invites`. - `source` (enum, required) — Where the event came from. `api` events were created through this API and the inbox is their organizer. `email` events were created from a calendar invitation (iMIP) received by the inbox; their organizer is the sender of the invitation. - Allowed values: `api`, `email` - `created_at` (datetime, required) — Time at which the event (or, for a date, the definition governing it) was created. - `updated_at` (datetime, required) — Time at which the event (or, for a date, the definition governing it) was last updated. - `series_id` (string, optional) — For `instance` events, the UUID of the series this date belongs to. - `original_start` (string, optional) — For `instance` events, the date's start as the series rule generated it, before any edit. - `original_start_at` (datetime, optional) — For `instance` events, `original_start` as a UTC instant. - `is_exception` (boolean, optional) — For `instance` events, `true` when this date was edited or moved, individually or by a `mode=future` change. - `description` (string, optional) — Description of the event. Omitted from agenda and instance list items. - `location` (string, optional) — Location of the event. - `metadata` (any, optional) — Your own JSON value for the event, usually an object. Never sent to attendees. Omitted from agenda and instance list items. - `recurrence` (Recurrence, optional) — For `series` events, the recurrence. - `attendees` (list of Attendee, optional) — Attendees of the event. Omitted from agenda and instance list items; `attendee_count` is always present. - `organizer_email` (string, optional) — Email address of the organizer. For `api` events, the inbox. - `origin_message_id` (string, optional) — For `email` events, the ID of the message whose invitation last created or updated the event. - `resource_revision` (integer, optional) — Present on `single` and `series` events, except agenda items and `calendar.event.starting` and `calendar.event.ending` payloads, which omit it. - `etag` (string, optional) — The event's or date's current version, also sent as the `ETag` response header. Send it in `If-Match` to make an update, delete or response conditional. Present on Get, Create, Update, Delete and Respond responses; list items and webhooks omit it. Treat it as opaque: a dated event's `etag` (`"occ-..."`) is not derived from `resource_revision`. ### Recurrence The recurrence of a series, as stored. - `rule` (string, required) — Normalized RRULE body, without the `RRULE:` prefix. - `exdates` (list of string, optional) - `rdates` (list of RecurrenceDate, optional) - `truncate_before` (string, optional) — Set when the series was ended with a `mode=future` delete: no date starting at or after this wall-clock time occurs. ### Attendee - `email` (string, required) — Email address of the attendee. Stored in lowercase. Must be unique within the event. - `name` (string, optional) — Display name of the attendee. At most 256 characters. - `status` (enum, optional) — Response status. Defaults to `needs_action`. - Allowed values: `needs_action`, `accepted`, `declined`, `tentative` - `role` (enum, optional) — Defaults to `required`. - Allowed values: `required`, `optional` - `comment` (string, optional) — Comment the attendee sent with their response. At most 4,096 UTF-8 bytes; on create or update, a longer comment is dropped rather than rejected. - `responded_at` (datetime, optional) — Time at which the attendee last responded. ### RecurrenceDate A wall-clock date or date-time, or (timed events only) a period. ### RecurrencePeriod An extra date (RDATE) given as a period. Specify exactly one of `end` or `duration`. - `start` (string, required) — A local wall-clock time without an offset, interpreted in the event's `timezone`. Timed events use `YYYY-MM-DDTHH:mm:ss` (for example `2026-10-15T09:00:00`). All-day events use `YYYY-MM-DD`. Years must be between 1900 and 9999. - `end` (string, optional) — A local wall-clock time without an offset, interpreted in the event's `timezone`. Timed events use `YYYY-MM-DDTHH:mm:ss` (for example `2026-10-15T09:00:00`). All-day events use `YYYY-MM-DD`. Years must be between 1900 and 9999. - `duration` (string, optional) — ISO 8601 duration, for example `PT30M`. ## Examples **Response** ```json { "count": 3, "limit": 3, "events": [ { "event_id": "7c4e9b2a-1f3d-4a8e-b6c5-2e9d0f1a8b47_t20261007T090000", "kind": "instance", "title": "Team standup", "status": "confirmed", "all_day": false, "start": "2026-10-07T09:00:00", "end": "2026-10-07T09:15:00", "timezone": "America/New_York", "duration_mode": "nominal", "duration_value": 900000, "start_at": "2026-10-07T13:00:00Z", "end_at": "2026-10-07T13:15:00Z", "attendee_count": 0, "uid": "7c4e9b2a-1f3d-4a8e-b6c5-2e9d0f1a8b47@agentmail.to", "sequence": 0, "source": "api", "created_at": "2026-10-01T16:25:00Z", "updated_at": "2026-10-01T16:25:00Z", "series_id": "7c4e9b2a-1f3d-4a8e-b6c5-2e9d0f1a8b47", "original_start": "2026-10-07T09:00:00", "original_start_at": "2026-10-07T13:00:00Z", "is_exception": false, "location": "https://meet.example.com/standup", "organizer_email": "scheduler@agentmail.to" }, { "event_id": "7c4e9b2a-1f3d-4a8e-b6c5-2e9d0f1a8b47_t20261009T090000", "kind": "instance", "title": "Team standup", "status": "confirmed", "all_day": false, "start": "2026-10-09T09:00:00", "end": "2026-10-09T09:15:00", "timezone": "America/New_York", "duration_mode": "nominal", "duration_value": 900000, "start_at": "2026-10-09T13:00:00Z", "end_at": "2026-10-09T13:15:00Z", "attendee_count": 0, "uid": "7c4e9b2a-1f3d-4a8e-b6c5-2e9d0f1a8b47@agentmail.to", "sequence": 0, "source": "api", "created_at": "2026-10-01T16:25:00Z", "updated_at": "2026-10-01T16:25:00Z", "series_id": "7c4e9b2a-1f3d-4a8e-b6c5-2e9d0f1a8b47", "original_start": "2026-10-09T09:00:00", "original_start_at": "2026-10-09T13:00:00Z", "is_exception": false, "location": "https://meet.example.com/standup", "organizer_email": "scheduler@agentmail.to" }, { "event_id": "7c4e9b2a-1f3d-4a8e-b6c5-2e9d0f1a8b47_t20261012T090000", "kind": "instance", "title": "Team standup", "status": "confirmed", "all_day": false, "start": "2026-10-12T09:00:00", "end": "2026-10-12T09:15:00", "timezone": "America/New_York", "duration_mode": "nominal", "duration_value": 900000, "start_at": "2026-10-12T13:00:00Z", "end_at": "2026-10-12T13:15:00Z", "attendee_count": 0, "uid": "7c4e9b2a-1f3d-4a8e-b6c5-2e9d0f1a8b47@agentmail.to", "sequence": 0, "source": "api", "created_at": "2026-10-01T16:25:00Z", "updated_at": "2026-10-01T16:25:00Z", "series_id": "7c4e9b2a-1f3d-4a8e-b6c5-2e9d0f1a8b47", "original_start": "2026-10-12T09:00:00", "original_start_at": "2026-10-12T13:00:00Z", "is_exception": false, "location": "https://meet.example.com/standup", "organizer_email": "scheduler@agentmail.to" } ], "next_page_token": "eyJzIjoiMjAyNi0xMC0xMlQxMzowMDowMFoifQ" } ``` **SDK Code** ```python import requests url = "https://api.agentmail.to/v0/inboxes/scheduler%40agentmail.to/calendar/agenda" querystring = {"after":"2026-10-07T00:00:00Z","before":"2026-10-16T00:00:00Z","limit":"3"} headers = {"Authorization": "Bearer "} response = requests.get(url, headers=headers, params=querystring) print(response.json()) ``` ```javascript const url = 'https://api.agentmail.to/v0/inboxes/scheduler%40agentmail.to/calendar/agenda?after=2026-10-07T00%3A00%3A00Z&before=2026-10-16T00%3A00%3A00Z&limit=3'; const options = {method: 'GET', headers: {Authorization: 'Bearer '}}; try { const response = await fetch(url, options); const data = await response.json(); console.log(data); } catch (error) { console.error(error); } ``` ```go package main import ( "fmt" "net/http" "io" ) func main() { url := "https://api.agentmail.to/v0/inboxes/scheduler%40agentmail.to/calendar/agenda?after=2026-10-07T00%3A00%3A00Z&before=2026-10-16T00%3A00%3A00Z&limit=3" req, _ := http.NewRequest("GET", url, nil) req.Header.Add("Authorization", "Bearer ") res, _ := http.DefaultClient.Do(req) defer res.Body.Close() body, _ := io.ReadAll(res.Body) fmt.Println(res) fmt.Println(string(body)) } ``` ```ruby require 'uri' require 'net/http' url = URI("https://api.agentmail.to/v0/inboxes/scheduler%40agentmail.to/calendar/agenda?after=2026-10-07T00%3A00%3A00Z&before=2026-10-16T00%3A00%3A00Z&limit=3") http = Net::HTTP.new(url.host, url.port) http.use_ssl = true request = Net::HTTP::Get.new(url) request["Authorization"] = 'Bearer ' response = http.request(request) puts response.read_body ``` ```java import com.mashape.unirest.http.HttpResponse; import com.mashape.unirest.http.Unirest; HttpResponse response = Unirest.get("https://api.agentmail.to/v0/inboxes/scheduler%40agentmail.to/calendar/agenda?after=2026-10-07T00%3A00%3A00Z&before=2026-10-16T00%3A00%3A00Z&limit=3") .header("Authorization", "Bearer ") .asString(); ``` ```php request('GET', 'https://api.agentmail.to/v0/inboxes/scheduler%40agentmail.to/calendar/agenda?after=2026-10-07T00%3A00%3A00Z&before=2026-10-16T00%3A00%3A00Z&limit=3', [ 'headers' => [ 'Authorization' => 'Bearer ', ], ]); echo $response->getBody(); ``` ```csharp using RestSharp; var client = new RestClient("https://api.agentmail.to/v0/inboxes/scheduler%40agentmail.to/calendar/agenda?after=2026-10-07T00%3A00%3A00Z&before=2026-10-16T00%3A00%3A00Z&limit=3"); var request = new RestRequest(Method.GET); request.AddHeader("Authorization", "Bearer "); IRestResponse response = client.Execute(request); ``` ```swift import Foundation let headers = ["Authorization": "Bearer "] let request = NSMutableURLRequest(url: NSURL(string: "https://api.agentmail.to/v0/inboxes/scheduler%40agentmail.to/calendar/agenda?after=2026-10-07T00%3A00%3A00Z&before=2026-10-16T00%3A00%3A00Z&limit=3")! as URL, cachePolicy: .useProtocolCachePolicy, timeoutInterval: 10.0) request.httpMethod = "GET" request.allHTTPHeaderFields = headers let session = URLSession.shared let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in if (error != nil) { print(error as Any) } else { let httpResponse = response as? HTTPURLResponse print(httpResponse) } }) dataTask.resume() ```