Update Event
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,timezoneandrecurrencecannot 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 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
Bearer authentication of the form Bearer <token>, where token is your auth token.
Path parameters
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.
Headers
The event's or date's current etag, from the latest read or write response. Optional; makes the update conditional; * matches any current version.
Query parameters
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.
Request
Changing all_day requires start, end and timezone in the same request. Not accepted for dated event IDs.
Set to null to clear.
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.
New end. For a one-off or series UUID, send it together with start. A dated ID accepts end alone.
Set to null to clear.
Replaces the metadata (any JSON value, usually an object). Set to null to clear.
Replaces the recurrence. Set to null to turn a series into a one-off event (only when no
date of it has been edited). Not accepted for dated event IDs.
When true, emails the updated invitation to every attendee. Only the organizer (an api
event) can send. Defaults to false.
New start. For a one-off or series UUID, send it together with end. Not accepted with mode=future.
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.
Response
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.
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.