AGagentmail-to
inboxes > calendar

Get Event

Changed on

Gets an event by its UUID, or one date of a recurring event by its dated ID (<uuid>_<slot>). A dated ID returns the date as it currently stands, including any edit to it, with kind: instance.

The response's etag (also the ETag header) is the value to send in If-Match to make an update, delete or response to this event or date conditional. Treat it as opaque.

Reads can trail a change made moments earlier by a few seconds; pass consistency=primary to read the latest state of an event or a date. A date that has already started or ended reads back as it ran, even if a later change to the series no longer produces it. Requires the calendar_event_read permission.

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

get/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

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

Response with status 200

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.

kind'single' | 'series' | 'instance' required

What the event object represents.

  • single: a one-off event, addressed by its UUID.
  • series: the definition of a recurring event, addressed by its UUID. It carries recurrence; start and end describe its first date.
  • instance: one date of a recurring event, addressed by its dated ID. It carries series_id, original_start and is_exception.
series_idstring

For instance events, the UUID of the series this date belongs to.

original_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.

original_start_atstring date-time

For instance events, original_start as a UTC instant.

is_exceptionboolean

For instance events, true when this date was edited or moved, individually or by a mode=future change.

titlestring required

Title of the event.

descriptionstring

Description of the event. Omitted from agenda and instance list items.

locationstring

Location of the event.

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

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 required

Whether this is an all-day event.

startstring required

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 required

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

duration_mode'nominal' | 'exact' required

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.

duration_valueinteger required

Length of the event, in milliseconds for timed events and in days for all-day events.

start_atstring date-time required

Start as a UTC instant. This is when calendar.event.starting is due.

end_atstring date-time required

End as a UTC instant. This is when calendar.event.ending is due.

attendee_countinteger required

Number of attendees.

response_status'needs_action' | 'accepted' | 'declined' | 'tentative'

The attendee's response to the invitation.

uidstring required

iCalendar UID of the event. Invitations about this event carry the same UID.

sequenceinteger required

iCalendar SEQUENCE number. It increases when a change to a one-off or series event affects what attendees see (time, status, title, description, location, recurrence or attendees). A change to a dated event increases it only when the change is sent with send_invites.

source'api' | 'email' required

Where the event came from. api events were created through this API and the inbox is their organizer. email events were created from a calendar invitation (iMIP) received by the inbox; their organizer is the sender of the invitation.

organizer_emailstring

Email address of the organizer. For api events, the inbox.

origin_message_idstring

For email events, the ID of the message whose invitation last created or updated the event.

resource_revisioninteger

Revision of the resource. It increases on every change. The resource's etag is "rv-<resource_revision>".

created_atstring date-time required

Time at which the event (or, for a date, the definition governing it) was created.

updated_atstring date-time required

Time at which the event (or, for a date, the definition governing it) was last updated.

etagstring

The event's or date's current version, also sent as the ETag response header. Send it in If-Match to make an update, delete or response conditional. Present on Get, Create, Update, Delete and Respond responses; list items and webhooks omit it. Treat it as opaque: a dated event's etag ("occ-...") is not derived from resource_revision.

Changes