AGagentmail-to
inboxes > calendar

Update Event

Changed on

Updates an event. Send only the fields to change. To make the update conditional, send the event's current etag in If-Match: a stale value returns 412. Without If-Match the update applies to the event as it is; a change that lands while it runs returns 409 race_condition, so retry. Send If-Match when replacing attendees, so you don't overwrite a response that arrived in the meantime.

  • One-off or series UUID: changes the event itself. For a series, the change applies to every date that has not been edited individually.
  • Dated ID (<uuid>_<slot>): changes one date (mode=single, the default) or that date and every later date (mode=future). all_day, timezone and recurrence cannot be sent for a dated ID.

Once a date has started, its start can no longer change (409 event_already_started), but its end and status can; for a one-off or series UUID, send the unchanged start with the new end. Once it has ended, only title, description, location, metadata and attendees can change. During the few seconds a date is starting, schedule changes return 409 event_starting; retry shortly.

Sends calendar.event.updated. With send_invites: true the organizer inbox also emails the updated invitation to every attendee. Requires the calendar_event_update permission.

Emailing attendees counts one send per attendee against the organization, pod and inbox send limits, charged before the change is saved; an over-limit request returns 429 rate_limit_exceeded and changes nothing.

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

patch/v0/inboxes/{inbox_id}/calendar/events/{event_id}

Request

  • Base URL
    https://api.agentmail.to
  • URL
    https://api.agentmail.to/v0/inboxes/{inbox_id}/calendar/events/{event_id}
  • Auth
    HTTP bearer

Path parameters

inbox_idstring required

The ID of the inbox.

event_idstring 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, <uuid>_<slot>: <uuid>_t20261015T090000 for a timed date (the original wall-clock start in the event's time zone) or <uuid>_d20261015 for an all-day date. Dated IDs are stable: moving a date keeps its original ID.

Query parameters

mode'single' | 'future'

Which dates a change to a dated event applies to. single (default) changes only this date. future changes this date and every later date of the series. Applies only to dated event IDs; sending mode with a one-off or series UUID is a 400.

Headers

If-Matchstring

The event's or date's current etag, from the latest read or write response. Optional; makes the update conditional; * matches any current version.

Request body

titlestring
descriptionstring nullable

Set to null to clear.

locationstring nullable

Set to null to clear.

metadataunknown
status'confirmed' | 'tentative' | 'cancelled'

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.

all_dayboolean

Changing all_day requires start, end and timezone in the same request. Not accepted for dated event IDs.

startstring

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.

endstring

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.

timezonestring

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.

duration_mode'nominal' | 'exact'

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.

send_invitesboolean

When true, emails the updated invitation to every attendee. Only the organizer (an api event) can send. Defaults to false.

Response

Response with status 200

operation_idstring required

ID of the change this request made. The calendar.event.created, calendar.event.updated, calendar.event.deleted or calendar.event.responded webhook for the change carries the same value as its event_id, so you can match webhooks to your own requests.

Changes