Delete Event
Deletes an event, or cancels dates of a recurring event.
- One-off or series UUID: deletes the event and every date of it. The event disappears
from reads immediately and is removed in the background; the response is
202with adeletion_id. A retry returns the samedeletion_idwhile removal runs (send the sameIdempotency-Key, or none and the samesend_invites); once it has finished, the event no longer exists and a retry returns404. Nocalendar.event.startingorcalendar.event.endingwebhook is sent for the event after the delete is accepted. - Dated ID (
<uuid>_<slot>): cancels that date (mode=single, the default) or that date and every later date (mode=future). Returns202with the cancelled date. Amode=futuredelete from the first date deletes the whole series and returns adeletion_idinstead. A date that is already running still gets itscalendar.event.ending.
Deleting a one-off or series event sends calendar.event.deleted. Cancelling dates sends
calendar.event.updated with the cancelled date. With send_invites=true the organizer
inbox also emails a cancellation to every attendee. Requires the calendar_event_delete
permission. To make the delete conditional, send the current etag in If-Match.
Emailing cancellations counts one send per attendee against the organization, pod and inbox
send limits, charged before the delete; an over-limit request returns 429
rate_limit_exceeded and deletes 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. Optional; makes the delete conditional; * matches any current version.
1 to 128 visible ASCII characters. Optional. Retrying a delete with the same key
returns the original result; without a key, retries of the same delete share one
derived from the event and send_invites, so a keyless retry that changes
send_invites is a different delete and returns 404 while removal runs. Keys are
unique across your organization: reusing one to delete a different event returns
409 idempotency_conflict.
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.
When true, emails a cancellation (iCalendar CANCEL) to every attendee. Only the organizer can send. Defaults to false.
Response
ID of an accepted deletion. While the event is being removed, retrying the same delete (with the
same Idempotency-Key, or none and the same send_invites) returns it again. Once removal has
finished, a retry returns 404.
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.