Skip to navigation
API ReferenceInboxesCalendar

Create Event

Beta

Creates a one-off or recurring event on the inbox’s calendar. Times are wall-clock values in timezone (the calendar’s default time zone if omitted); the response also gives each boundary as a UTC instant in start_at and end_at.

calendar.event.created is sent once the event is stored, then calendar.event.starting and calendar.event.ending as each date begins and ends. With send_invites: true the inbox also emails an invitation to every attendee.

Pass client_id to make retries safe: repeating the request with the same client_id and body returns the original event with status 200 instead of 201, for as long as the event exists.

With send_invites: true, each attendee counts as one send against the organization, pod and inbox send limits, charged before the event is stored. An over-limit request returns 429 rate_limit_exceeded and creates nothing. A replay of an earlier create is not charged again.

The event’s etag is the value to send in If-Match to make a later update or delete conditional. Requires the calendar_event_create permission.

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

AuthorizationBearer

Bearer authentication of the form Bearer <token>, where token is your auth token.

Path parameters

inbox_idstringRequired
The ID of the inbox.

Request

This endpoint expects an object.
titlestringRequired
Title of the event. 1 to 1,000 characters.
startstringRequired

Local start time in timezone: YYYY-MM-DDTHH:mm:ss for timed events, YYYY-MM-DD for all-day events. For a recurring event, this is the first date.

endstringRequired

Local end time in timezone, in the same format as start. For timed events it must be after start; for all-day events it is the last day (inclusive) and can equal start. One-off events can last up to 366 days; each date of a recurring event up to 31 days.

client_idstringOptional

Your idempotency key for this create. Retrying with the same client_id and the same body returns the original event with 200 instead of creating a second one, for as long as the event exists (404 once it has been deleted). Reusing it with a different body is a 409 idempotency_conflict.

descriptionstringOptional
Description of the event. At most 65,536 bytes.
locationstringOptional
Location of the event. At most 1,024 characters.
metadataanyOptional

Your own JSON value (usually an object), returned on reads and in webhooks (except agenda and instance list items, and the webhook for a date cancelled with DELETE). Never sent to attendees. At most 16,384 bytes serialized.

statusenumOptional

Defaults to confirmed.

Allowed values:
all_daybooleanOptional

Set to true for an all-day event. Defaults to false.

timezonestringOptional

Time zone of start and end. Defaults to the calendar's timezone.

duration_modeenumOptional

Timed events only. Defaults to exact for one-off events and nominal for recurring events.

Allowed values:
recurrenceobjectOptional
Makes this a recurring event.
attendeeslist of objectsOptional
Attendees of the event. At most 100.
send_invitesbooleanOptional

When true, the inbox emails an invitation (iCalendar REQUEST) to every attendee. Defaults to false.

Response

This endpoint returns an object.
eventobject

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.

operation_idstring

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.

Errors

400
Validation Error
403
Forbidden Error
404
Not Found Error
409
Conflict Error
413
Payload Too Large Error
429
Rate Limit Error