---
title: "Get Calendar"
method: GET
path: "/v0/inboxes/{inbox_id}/calendar"
tags: ["inboxes > calendar"]
---

# Get Calendar

`GET /v0/inboxes/{inbox_id}/calendar`

## Request

- Base URL: `https://api.agentmail.to`
- URL: `https://api.agentmail.to/v0/inboxes/{inbox_id}/calendar`
- Auth: HTTP bearer

Gets the inbox's calendar. Every inbox has one calendar, so this works before any event is
created. Its `etag` (also the `ETag` response header) is the value to send in `If-Match` to
make an update conditional.

Requires the `calendar_read` permission. Calendar is available in US production
(`api.agentmail.to`) but not yet in EU production (`api.agentmail.eu`), which returns `403`.

## Path parameters

- `inbox_id` string, required: The ID of the inbox.

## Query parameters

- `consistency` 'eventual' | 'primary': 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.

## Response `200`

Response with status 200

- CalendarCalendar: An inbox's calendar. Every inbox has exactly one calendar; it exists from the moment the inbox does and is deleted with it.
  - `inbox_id` string, required: The ID of the inbox.
  - `timezone` string, required: IANA time zone name, for example `America/New_York`, `Europe/London` or `UTC`. Requests accept any capitalization and IANA aliases such as `US/Eastern`. The calendar stores and returns the canonical name, which for some zones is an older spelling: `Asia/Kolkata` is returned as `Asia/Calcutta`. Abbreviations such as `PST` and Windows names such as `Pacific Standard Time` are rejected.
  - `event_count` integer, required: Number of one-off and recurring events on the calendar. Each recurring event counts once.
  - `created_at` string, date-time, required: Time at which the calendar was created. The calendar exists from the moment the inbox does, so this is the inbox's creation time.
  - `updated_at` string, date-time, required: Time at which the calendar was last updated.
  - `etag` string, required: The calendar's current version, also sent as the `ETag` response header. Send it in `If-Match` to make an update conditional.

## Other responses

- `400`: Error response with status 400
- `403`: Calendar isn't available in this region (EU production), or the API key lacks the required calendar permission.
- `404`: Error response with status 404

## Changes

- **2026-10-16** `3f5c7830c952`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/agentmail-to/apis/api/changes/v0/inboxes/:inbox_id/calendar/get.md)

---

[API](https://skmtc.dev/agentmail-to/apis/api.md) - [All operations](https://skmtc.dev/agentmail-to/apis/api/llms.txt) - [OpenAPI document](https://skmtc.dev/agentmail-to/apis/api/revisions/a9792efe7bdf?raw)