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

# Update Calendar

`PATCH /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

Updates the calendar's default time zone. Existing events keep their own `timezone`; only
events created later without a `timezone` use the new default.

Requires the `calendar_update` permission. To make the update conditional, send the
calendar's current `etag` in `If-Match`: a stale value returns `412`. Without `If-Match` the
update applies to the calendar as it is.

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.

## Headers

- `If-Match` string

## Request body

- object
  - `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.

## 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
- `409`: Error response with status 409
- `412`: The resource changed since the `If-Match` value was read. Fetch it again, reapply the change, and retry with the new `etag`.
- `413`: The request body is too large (8 KB for calendar settings, 128 KB for events).

## Changes

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

[Operation history](https://skmtc.dev/agentmail-to/apis/api/changes/v0/inboxes/:inbox_id/calendar/patch.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)