Calendar
Every operation in this group: what it accepts, what it returns and the errors it can answer with.
Operations
Events and invitations, as the Calendar page of the app shows them: list a window, read an event or the one a thread carries, put events on the calendar and change them, call off a meeting, and answer an invitation. A change that invites, updates or cancels attendees, and every answer, goes out by email, so it also needs emails:send.
GET/calendar/events
List occurrences in a window
from and to are REQUIRED. Occurrences are expanded from recurrence rules, so a calendar has no meaningful unbounded listing. A default window would turn an infinite series into a question with no answer. At most a year apart.
Lists your own events: the ones you made and the ones an address of yours organises or attends. For the workspace owner and their keys, an address counts as theirs unless it was given to a teammate. Set includeTeam to true to add the rest of the workspace, apart from events somebody marked private. A member and a narrowed key always get their own view, whatever includeTeam says.
Requires the calendar:read scope.
Query parameters
fromstringRequiredStart of the window.
Formatdate-timetostringRequiredEnd of the window, after
fromand at most 366 days later.Formatdate-timetimezonestringRequiredIANA zone. Decides what an all-day event means.
includeTeambooleanAdds the events of the rest of the workspace, apart from the ones marked private. Only the workspace owner and their keys see more with it.
DefaultfalseqstringWords to look for in the title, the place and the organiser. Only events that hold every word come back, so search a long window, at most a year, to find an event by name.
Up to 200 characterslimitintegerRows per page, 1 to 100.
At least 1At most 100Default25cursorstringThe previous page's
nextCursor, passed back as it came. It is opaque: it holds where the last row sat in this list's order, so a row deleted or edited between pages never breaks the walk, and the next page starts at the first row that sorts after it. A value this list did not hand out is a 400invalid_cursor.
Returns
A page of occurrences, sorted by start and then by event id, with hasMore and nextCursor. Send the same from, to, timezone and q with every cursor. Nothing in the window is dropped: a series repeats at most once a day, so it gives at most one occurrence per day of the window, and every one is reachable through the pages. The cursor holds the start and event id of the last row, so an event deleted or moved between pages never breaks the walk.
Errors
The errors every operation can return400401403404422429500Error catalog
Also available in
- TypeScript
nextmail.calendar.listEvents()nextmail.calendar.listAllEvents()nextmail.calendar.iterateEvents()- Python
calendar.list_events()calendar.list_all_events()calendar.iterate_events()- Ruby
calendar.list_eventscalendar.list_all_eventscalendar.iterate_events- PHP
calendar->listEventscalendar->listAllEventscalendar->iterateEvents- Go
Calendar.ListEventsCalendar.ListAllEventsCalendar.IterateEvents- Java
calendar().listEventscalendar().listAllEventscalendar().iterateEvents- C#
Calendar.ListEventsAsyncCalendar.ListAllEventsAsyncCalendar.IterateEventsAsync- CLI
nextmail calendar list-events- MCP
listCalendarEvents
POST/calendar/events
Create an event
Puts an event on the calendar, as New event on the Calendar page of the app does. start and end are ISO 8601 with a zone, and timezone is the IANA zone the event belongs to, UTC unless you say. recurrence takes an RRULE such as FREQ=WEEKLY;BYDAY=MO, and reminders the minutes before the start.
With attendees, an invitation goes to each of them from the address in from, which has to be one the key or app may send as, so the call also needs emails:send. sendInvites: false keeps the change to your own calendar.
Requires the calendar:write scope.
Request body
summarystringRequiredThe title, 1 to 255 characters.
1 to 255 charactersdescriptionstringNotes about the event, up to 8,000 characters.
Up to 8000 characterslocationstringWhere it is: a room, an address or a link.
Up to 255 charactersurlstringA link that belongs to the event.
Up to 2000 charactersFormaturimeetingUrlstringA link to the video call, such as a Zoom, Meet or Teams address. It goes into the invitation, so guests see a Join button in their calendar too. Send an empty string to take it off.
Up to 2000 charactersstartstringRequiredWhen it starts, a
Dateor ISO 8601 with a zone.Formatdate-timeendstringRequiredWhen it ends, after
startand at most two years later.Formatdate-timeallDaybooleanWhether it fills whole days.
startandendthen mark the days.timezonestringThe IANA zone the event belongs to,
UTCunless you say.1 to 64 charactersrecurrencestringAn RRULE such as
FREQ=WEEKLY;BYDAY=MOwhen it repeats.Up to 512 charactersattendeesobject[]Up to 200 people to invite, each
{ email, name?, optional? }.Up to 200 itemsemailstringRequired- Up to 320 charactersFormat
email namestring- Up to 128 characters
optionalboolean
remindersobject[]Up to five reminders, each
{ minutesBefore, action? }.Up to 5 itemsminutesBeforeintegerRequired- At least 0At most 40320
actionstring- One of
"DISPLAY""EMAIL""AUDIO"
transparencystringOPAQUEshows you busy andTRANSPARENTfree.One of"OPAQUE""TRANSPARENT"visibilitystringPUBLIC,PRIVATEorCONFIDENTIAL.One of"PUBLIC""PRIVATE""CONFIDENTIAL"sendInvitesbooleanFalse keeps the change to your own calendar, and sends nothing.
fromstringThe address the invitations come from. It has to be one the key may send as.
Up to 320 characters
Returns
The event, with its attendees.
Errors
- 403
from_address_forbidden: the key or app may not send asfrom.insufficient_scopewhen invitations would go out andemails:sendis missing.
The errors every operation can return400401404422429500Error catalog
Also available in
GET/calendar/events/{id}
Retrieve an event
The event with its attendees and their responses. rawIcs is omitted. Everything understood in it is already structured here, and /ics serves the document.
Requires the calendar:read scope.
Path parameters
idstringRequiredEvent id, the
eventIdof an occurrence, such ascal_followed by 24 hex characters.
Returns
The event.
Errors
The errors every operation can return400401403404422429500Error catalog
Also available in
PATCH/calendar/events/{id}
Change an event
Changes an event you organise. A field left out keeps its value, and attendees replaces the whole list. Everyone invited gets the updated invitation.
For a repeating event, scope says which dates change, as the app asks when you edit one date: occurrence changes only the date that starts at occurrenceStart, following that date and every one after it (they become a new series, and the old one ends the day before), and series all of them, with a new start or end moving every date by the same amount.
With attendees, an invitation goes to each of them from the address in from, which has to be one the key or app may send as, so the call also needs emails:send. sendInvites: false keeps the change to your own calendar.
Requires the calendar:write scope.
Path parameters
idstringRequiredThe event id from
GET /calendar/events.
Request body
summarystringThe title, 1 to 255 characters.
1 to 255 charactersdescriptionstringNotes about the event, up to 8,000 characters.
Up to 8000 characterslocationstringWhere it is: a room, an address or a link.
Up to 255 charactersurlstringA link that belongs to the event.
Up to 2000 charactersFormaturimeetingUrlstringA link to the video call, such as a Zoom, Meet or Teams address. It goes into the invitation, so guests see a Join button in their calendar too. Send an empty string to take it off.
Up to 2000 charactersstartstringWhen it starts, a
Dateor ISO 8601 with a zone.Formatdate-timeendstringWhen it ends, after
startand at most two years later.Formatdate-timeallDaybooleanWhether it fills whole days.
startandendthen mark the days.timezonestringThe IANA zone the event belongs to,
UTCunless you say.1 to 64 charactersrecurrencestringAn RRULE such as
FREQ=WEEKLY;BYDAY=MOwhen it repeats.Up to 512 charactersattendeesobject[]Up to 200 people to invite, each
{ email, name?, optional? }. It replaces the whole list.Up to 200 itemsemailstringRequired- Up to 320 charactersFormat
email namestring- Up to 128 characters
optionalboolean
remindersobject[]Up to five reminders, each
{ minutesBefore, action? }.Up to 5 itemsminutesBeforeintegerRequired- At least 0At most 40320
actionstring- One of
"DISPLAY""EMAIL""AUDIO"
transparencystringOPAQUEshows you busy andTRANSPARENTfree.One of"OPAQUE""TRANSPARENT"visibilitystringPUBLIC,PRIVATEorCONFIDENTIAL.One of"PUBLIC""PRIVATE""CONFIDENTIAL"sendInvitesbooleanFalse keeps the change to your own calendar, and sends nothing.
fromstringThe address the invitations come from. It has to be one the key may send as.
Up to 320 charactersscopestringWhich dates the change reaches when the event repeats:
occurrencefor the one date inoccurrenceStart,followingfor that date and every one after it, orseriesfor all of them. Left out, the change reaches the event or date the id names.One of"occurrence""following""series"occurrenceStartstringThe start of the date you mean, as it appears in the list of events. Needed with
occurrenceandfollowing.Formatdate-time
Returns
The event as it stands now.
Errors
- 403
not_organizer: the event was organised by somebody else, so you can only answer it.from_address_forbidden: the key or app may not send asfrom.- 409
event_cancelled: the meeting was called off.
The errors every operation can return400401404422429500Error catalog
Also available in
DELETE/calendar/events/{id}
Remove an event
Removes an event from the calendar for good, as Remove does in the app. Nobody else is told: to call off a meeting with others in it, use POST /calendar/events/{id}/cancel. For a repeating event, scope and occurrenceStart remove one date or that date and every one after it.
Requires the calendar:write scope.
Path parameters
idstringRequiredThe event id from
GET /calendar/events.
Query parameters
scopestringWhich dates the change reaches when the event repeats:
occurrencefor the one date inoccurrenceStart,followingfor that date and every one after it, orseriesfor all of them. Left out, the change reaches the event or date the id names.One of"occurrence""following""series"occurrenceStartstringThe start of the date you mean, as it appears in the list of events. Needed with
occurrenceandfollowing.Formatdate-time
Returns
The event is gone.
Errors
- 403
not_organizer: the event was organised by somebody else.
The errors every operation can return400401404422429500Error catalog
Also available in
GET/calendar/events/{id}/ics
The event as an .ics document
Served as text/calendar with NO METHOD parameter. A METHOD makes a document actionable (a client seeing method=REQUEST draws accept/decline and can reply to the organiser), and this endpoint has no authority to invite anybody on the workspace behalf. It states what the event currently is.
Requires the calendar:read scope.
Path parameters
idstringRequiredEvent id, the
eventIdof an occurrence.
Returns
text/calendarAn iCalendar document.
Errors
The errors every operation can return400401403404422429500Error catalog
Also available in
POST/calendar/events/{id}/cancel
Cancel a meeting
Calls off a meeting you organise, as Cancel meeting does in the app. It stays on the calendar with status CANCELLED, and everyone invited is told it is off, from the address in from, so a meeting with attendees also needs emails:send. For a repeating meeting, scope and occurrenceStart call off one date, or that date and every one after it, and guests get the matching update. The body is optional.
Requires the calendar:write scope.
Path parameters
idstringRequiredThe event id from
GET /calendar/events.
Request body
fromstringThe address the cancellation comes from. It has to be one the key may send as.
Up to 320 charactersnotifyGuestsbooleanscopestringWhich dates the change reaches when the event repeats:
occurrencefor the one date inoccurrenceStart,followingfor that date and every one after it, orseriesfor all of them. Left out, the change reaches the event or date the id names.One of"occurrence""following""series"occurrenceStartstringThe start of the date you mean, as it appears in the list of events. Needed with
occurrenceandfollowing.Formatdate-time
Returns
The event, cancelled.
Errors
- 403
not_organizer: the event was organised by somebody else.from_address_forbidden: the key or app may not send asfrom.
The errors every operation can return400401404422429500Error catalog
Also available in
POST/calendar/events/{id}/respond
Answer an invitation
Accepts, declines or tentatively accepts an invitation, as the buttons of an invitation in the app do. The answer goes to the organiser by email from the invited address the key or app may send as, or from respondingAs when the invitation went to more than one of yours. Send proposedStart and proposedEnd together to propose a new time with your answer, as Propose a new time does in the app: the organiser gets a counter-proposal and decides.
Requires the calendar:write and emails:send scopes.
Path parameters
idstringRequiredThe event id from
GET /calendar/events.
Request body
responsestringRequiredACCEPTED,DECLINEDorTENTATIVE.One of"ACCEPTED""DECLINED""TENTATIVE"respondingAsstringWhich of your invited addresses answers, when there is more than one.
Up to 320 charactersproposedStartstringA new start to propose with your answer, sent together with
proposedEnd.Formatdate-timeproposedEndstringThe end of the proposed time.
Formatdate-timenotifyGuestsboolean
Returns
The event, with your answer.
Errors
- 403
not_invited: the event did not inviterespondingAs, or any address the key or app may send as.- 409
event_cancelled: the meeting was called off.reply_not_sent: the answer could not be sent to the organiser, so nothing changed.
The errors every operation can return400401404422429500Error catalog
Also available in
POST/calendar/events/{id}/decline-proposal
Decline a proposed time
Keeps the original time of a meeting you organise after a guest proposed another one, as Decline in the proposal on the event does in the app. The guest is told by email from from, or from the organising address. To take the proposed time instead, change the event with PATCH /calendar/events/{id}.
Requires the calendar:write and emails:send scopes.
Path parameters
idstringRequiredThe event id from
GET /calendar/events.
Request body
attendeestringRequiredThe guest whose proposal you decline, by email address.
Up to 320 charactersFormatemailfromstringThe address the answer is sent from, when it is not the organising address.
Up to 320 characters
Returns
The event, with the proposal cleared.
Errors
- 403
not_organizer: the event was organised by somebody else.event_read_only: the event comes from a calendar you subscribe to.- 404
proposal_not_found: that guest has not proposed a new time.event_not_found: no such event.
The errors every operation can return400401422429500Error catalog
Also available in
POST/calendar/events/{id}/hide
Hide an event from your calendar
Takes an event off your own calendar and leaves it where it is for everyone else, as Hide from my calendar does in the app. Use it for an invitation that reached you through a shared address, or one you may not remove. It stops its reminders for you too. POST /calendar/events/{id}/unhide brings it back.
Requires the calendar:write scope.
Path parameters
idstringRequiredThe event id from
GET /calendar/events.
Returns
The event, hidden for you.
Errors
The errors every operation can return400401403404422429500Error catalog
Also available in
POST/calendar/events/{id}/unhide
Show a hidden event again
Puts an event you hid back on your calendar, as Show on my calendar does on the invitation in the app.
Requires the calendar:write scope.
Path parameters
idstringRequiredThe event id from
GET /calendar/events.
Returns
The event, on your calendar again.
Errors
The errors every operation can return400401403404422429500Error catalog
Also available in
GET/calendar/free-busy
Free and busy times
When the people you name are busy, as Find a time in the event editor of the app shows it. Each address of the workspace shows the busy times of the person who holds it, from their events, the invitations they have not declined, their subscribed calendars and their bookings, without any detail. Add durationMinutes to get suggestions: the first times everyone known is free. A key or app limited to some addresses is refused, since the answer reads whole calendars.
Requires the calendar:read scope.
Query parameters
fromstringRequiredThe start of the window.
Formatdate-timetostringRequiredA free and busy window may span at most 31 days.
Formatdate-timeemailsstringRequiredThe addresses to look up, at most 20. An address of the workspace shows when the person who holds it is busy; any other address comes back with
knownfalse. Separate them with commas.timezonestringIANA zone the suggested times keep to working hours in.
Default"UTC"durationMinutesintegerThe length of the meeting in minutes. With it,
suggestionslists the first times everyone known is free, on weekdays between 09:00 and 17:00 intimezone.At least 5At most 480
Returns
When each person is busy, and the suggested times.
Errors
- 422
capability_unsupported: the key or app is limited to some addresses.invalid_parameter: the window, an address or the duration is not valid.
The errors every operation can return400401403404429500Error catalog
Also available in
GET/calendar/feeds
List calendar links
The secret links that publish your calendar to other calendar apps, as Share in the calendar settings of the app lists them. Anyone with a link can read what it shows, so treat url and webcalUrl like passwords.
Requires the calendar:read scope.
Returns
Your calendar links.
Errors
The errors every operation can return400401403404422429500Error catalog
Also available in
POST/calendar/feeds
Create a calendar link
Makes a secret link that publishes your calendar as an iCalendar feed, for Google Calendar (From URL), Outlook (Subscribe from web) or Apple Calendar (New subscription). full shows every detail, busy only the times you are busy. The calendar app checks the link again on its own schedule, usually every few hours.
Requires the calendar:write scope.
Request body
namestringRequiredThe name calendar apps show for the calendar, up to 100 characters.
1 to 100 charactersmodestringRequiredfullfor every detail,busyfor busy times only.One of"full""busy"
Returns
The new link.
Errors
- 409
calendar_feed_limit: you already keep the most links one person may.
The errors every operation can return400401403404422429500Error catalog
Also available in
DELETE/calendar/feeds/{id}
Delete a calendar link
Turns a calendar link off for good. Calendar apps that subscribed to it stop getting updates.
Requires the calendar:write scope.
Path parameters
idstringRequiredThe calendar link id.
Returns
The link is gone.
Errors
- 404
calendar_feed_not_found: no link of yours has that id.
The errors every operation can return400401403422429500Error catalog
Also available in
POST/calendar/feeds/{id}/reset
Reset a calendar link
Replaces the secret in a calendar link, so the old address stops working everywhere it was shared. Paste the new address into the calendar apps you still want to update.
Requires the calendar:write scope.
Path parameters
idstringRequiredThe calendar link id.
Returns
The link with its new address.
Errors
- 404
calendar_feed_not_found: no link of yours has that id.
The errors every operation can return400401403422429500Error catalog
Also available in
GET/calendar/subscriptions
List calendar subscriptions
The other calendars you subscribe to by link, such as a Google or Outlook calendar address, a team rota or public holidays, as Other calendars in the app lists them. Their events show on your calendar, read-only.
Requires the calendar:read scope.
Returns
Your subscriptions.
Errors
The errors every operation can return400401403404422429500Error catalog
Also available in
- TypeScript
nextmail.calendar.listSubscriptions()- Python
calendar.list_subscriptions()- Ruby
calendar.list_subscriptions- PHP
calendar->listSubscriptions- Go
Calendar.ListSubscriptions- Java
calendar().listSubscriptions- C#
Calendar.ListSubscriptionsAsync- CLI
nextmail calendar list-subscriptions- MCP
listCalendarSubscriptions
POST/calendar/subscriptions
Subscribe to a calendar
Adds a calendar by its iCalendar link: an https, http or webcal address, such as the secret address of a Google calendar or a published Outlook calendar. It is read at once, then again about every half hour. name defaults to the name the calendar gives itself.
Requires the calendar:write scope.
Request body
urlstringRequiredThe calendar link,
https,httporwebcal.1 to 2048 charactersnamestringThe name to show, up to 100 characters.
1 to 100 characterscolorstringThe colour of its events, from
CALENDAR_COLORS.One of"blue""sky""teal""green""lime""yellow""orange""red""pink""purple""gray"
Returns
The subscription, with its first events read.
Errors
- 409
calendar_subscription_exists: you already subscribe to that address.calendar_subscription_limit: you already subscribe to the most calendars one person may.- 422
calendar_subscription_url_invalid: not a public https, http or webcal link.calendar_subscription_unreadable: nothing at the address read as a calendar.
The errors every operation can return400401403404429500Error catalog
Also available in
- TypeScript
nextmail.calendar.createSubscription()- Python
calendar.create_subscription()- Ruby
calendar.create_subscription- PHP
calendar->createSubscription- Go
Calendar.CreateSubscription- Java
calendar().createSubscription- C#
Calendar.CreateSubscriptionAsync- CLI
nextmail calendar create-subscription- MCP
subscribeToCalendar
PATCH/calendar/subscriptions/{id}
Change a calendar subscription
Renames a subscription or gives it another colour.
Requires the calendar:write scope.
Path parameters
idstringRequiredThe subscription id.
Request body
namestringThe new name, up to 100 characters.
1 to 100 characterscolorstringThe new colour, from
CALENDAR_COLORS.One of"blue""sky""teal""green""lime""yellow""orange""red""pink""purple""gray"
Returns
The subscription as it stands now.
Errors
- 404
calendar_subscription_not_found: no subscription of yours has that id.
The errors every operation can return400401403422429500Error catalog
Also available in
- TypeScript
nextmail.calendar.updateSubscription()- Python
calendar.update_subscription()- Ruby
calendar.update_subscription- PHP
calendar->updateSubscription- Go
Calendar.UpdateSubscription- Java
calendar().updateSubscription- C#
Calendar.UpdateSubscriptionAsync- CLI
nextmail calendar update-subscription- MCP
updateCalendarSubscription
DELETE/calendar/subscriptions/{id}
Unsubscribe from a calendar
Removes a subscription and every event it brought onto your calendar.
Requires the calendar:write scope.
Path parameters
idstringRequiredThe subscription id.
Returns
The subscription is gone.
Errors
- 404
calendar_subscription_not_found: no subscription of yours has that id.
The errors every operation can return400401403422429500Error catalog
Also available in
- TypeScript
nextmail.calendar.deleteSubscription()- Python
calendar.delete_subscription()- Ruby
calendar.delete_subscription- PHP
calendar->deleteSubscription- Go
Calendar.DeleteSubscription- Java
calendar().deleteSubscription- C#
Calendar.DeleteSubscriptionAsync- CLI
nextmail calendar delete-subscription- MCP
unsubscribeFromCalendar
POST/calendar/subscriptions/{id}/refresh
Refresh a calendar subscription
Reads a subscribed calendar again now instead of waiting for the next half-hourly read, and restarts one that stopped after repeated failures.
Requires the calendar:write scope.
Path parameters
idstringRequiredThe subscription id.
Returns
The subscription after the read.
Errors
- 404
calendar_subscription_not_found: no subscription of yours has that id.- 429
calendar_subscription_refresh_too_soon: it was read moments ago.rate_limited: the key or app made more than 600 requests in 60 seconds. Wait for the seconds inRetry-After.
The errors every operation can return400401403422500Error catalog
Also available in
- TypeScript
nextmail.calendar.refreshSubscription()- Python
calendar.refresh_subscription()- Ruby
calendar.refresh_subscription- PHP
calendar->refreshSubscription- Go
Calendar.RefreshSubscription- Java
calendar().refreshSubscription- C#
Calendar.RefreshSubscriptionAsync- CLI
nextmail calendar refresh-subscription- MCP
refreshCalendarSubscription
GET/threads/{id}/event
The event a thread carries
The calendar event that came with an invitation in the thread, as the invitation card of the reading pane shows it. A thread with no event, or one the key or app does not reach, is a 404. Answer it with POST /calendar/events/{id}/respond.
Requires the calendar:read scope.
Path parameters
idstringRequiredThe thread id.
Returns
The event.
Errors
The errors every operation can return400401403404422429500Error catalog
Also available in
GET/calendar/imports
List calendar imports
The calendar files and calendars brought in, newest first, each with what it added and what it left out. Paging is keyset: pass nextCursor back as cursor while hasMore is true.
Requires the calendar:read scope.
Query parameters
limitintegerRows per page, 1 to 100.
At least 1At most 100Default25cursorstringThe previous page's
nextCursor, passed back as it came. It is opaque: it holds where the last row sat in this list's order, so a row deleted or edited between pages never breaks the walk, and the next page starts at the first row that sorts after it. A value this list did not hand out is a 400invalid_cursor.
Returns
One page of calendar imports.
Errors
The errors every operation can return400401403404422429500Error catalog
Also available in
- TypeScript
nextmail.calendar.listImports()nextmail.calendar.listAllImports()nextmail.calendar.iterateImports()- Python
calendar.list_imports()calendar.list_all_imports()calendar.iterate_imports()- Ruby
calendar.list_importscalendar.list_all_importscalendar.iterate_imports- PHP
calendar->listImportscalendar->listAllImportscalendar->iterateImports- Go
Calendar.ListImportsCalendar.ListAllImportsCalendar.IterateImports- Java
calendar().listImportscalendar().listAllImportscalendar().iterateImports- C#
Calendar.ListImportsAsyncCalendar.ListAllImportsAsyncCalendar.IterateImportsAsync- CLI
nextmail calendar list-imports- MCP
listCalendarImports
POST/calendar/imports
Import a calendar file
Takes an iCalendar (.ics) file as the request body and queues it. Its events become events of your own that you can edit, and nobody on them is sent anything, now or when you change them later, unless you ask for that on the change. Poll GET /calendar/imports/{id} until status is completed.
The file may be 10 MB and hold 25,000 events. Several calendars in one file are merged, and the report keeps their names. An event whose UID is already in the workspace is skipped and counted, never overwritten, so sending the same file twice adds nothing.
Requires the calendar:write scope.
Query parameters
filenamestringThe name to show for the file in the list of imports.
Up to 255 characters
Request body
Content typetext/calendar, application/octet-stream
Returns
The import, with status queued.
Errors
- 400
not_a_calendar_file: the body is not an iCalendar file.item_import_empty: the body is empty.too_many_events: the file holds more than 25,000 events.- 413
item_import_too_large: the file is over 10 MB.
The errors every operation can return401403404422429500Error catalog
Also available in
GET/calendar/imports/{id}
Get a calendar import
One calendar import with its counts and its report: the calendars it read, how many events it left out and why, and up to 20 of the events it left out.
Requires the calendar:read scope.
Path parameters
idstringRequiredCalendar import id,
iimp_followed by 24 hex characters.
Returns
The import.
Errors
- 404
item_import_not_found: no such import.
The errors every operation can return400401403422429500Error catalog
Also available in
POST/calendar/imports/{id}/undo
Remove what a calendar import added
Deletes every event the import added, changed since or not, and marks the import undone. Nobody is told. Events that were skipped because they were already here are not touched.
Requires the calendar:write scope.
Path parameters
idstringRequiredCalendar import id,
iimp_followed by 24 hex characters.
Returns
The import, with status undone.
Errors
- 404
item_import_not_found: no such import.- 409
item_import_not_undoable: it is still running or was already removed.
The errors every operation can return400401403422429500Error catalog
Also available in
Objects
CalendarEventobject
objectstringRequired- One of
"calendar_event" idstringRequireduidstringRequiredThe iCalendar UID every copy of the event shares.
sequenceinteger- At least 0
summarystring- Can be null
descriptionstring- Can be null
locationstring- Can be null
urlstring- Can be null
meetingUrlstringThe link to the video call, which the apps show as a Join button.
Can be nullstartstringRequired- Format
date-time endstringRequired- Format
date-time allDaybooleantimezonestring- Can be null
recurrencestringThe RRULE, when it repeats.
Can be nullexdatesstring[]Occurrences left out: an instant, or a date for an all-day event.
rdatesstring[]Extra occurrences outside the rule: an instant, or a date for an all-day event.
recurrenceIdstringFor one changed occurrence of a repeating event, the start it replaces.
Can be nullFormatdate-timesubscriptionIdstringThe calendar subscription it comes from, or null for your own calendar.
Can be nullstatusstringRequiredCONFIRMED,TENTATIVEorCANCELLED.transparencystringvisibilitystringorganizerobject- Can be null
emailstringnamestring- Can be null
isOrganizerbooleanWhether you organise it, and so may change it.
hiddenbooleanWhether you hid it from your own calendar with
POST /calendar/events/{id}/hide. OnlyGET /calendar/events/{id}says.sourcestringmessageIdstring- Can be null
threadIdstring- Can be null
alarmsobject[]minutesBeforeintegeractionstring
attendeesobject[]Requiredobjectstring- One of
"calendar_attendee" emailstringnamestring- Can be null
partstatstringNEEDS-ACTION,ACCEPTED,DECLINEDorTENTATIVE.rolestringrsvpbooleancutypestring- Can be null
respondedAtstring- Can be nullFormat
date-time proposedStartstringThe start this guest proposed instead, until the organiser answers.
Can be nullFormatdate-timeproposedEndstring- Can be nullFormat
date-time
createdAtstring- Format
date-time updatedAtstring- Format
date-time
CalendarEventHiddenobject
objectstringRequired- One of
"calendar_event" idstringRequireduidstringRequiredThe iCalendar UID. Hiding reaches every date of it.
hiddenbooleanRequired
CalendarFeedobject
objectstringRequired- One of
"calendar_feed" idstringRequirednamestringRequiredThe name calendar apps show for the calendar.
modestringRequiredfullshows every detail,busyonly when you are busy.One of"full""busy"urlstringRequiredThe https address to paste into a calendar app.
webcalUrlstringRequiredThe same address as a webcal link, which opens a calendar app.
readCountintegerRequiredRoughly how often calendar apps have read it.
At least 0lastReadAtstringRequired- Can be nullFormat
date-time createdAtstringRequired- Format
date-time
CalendarFeedListobject
objectstring- One of
"list" dataCalendarFeed[]
CalendarFreeBusyobject
objectstringRequired- One of
"calendar_free_busy" fromstringRequired- Format
date-time tostringRequired- Format
date-time timezonestringRequiredpeopleobject[]RequiredemailstringRequiredknownbooleanRequiredWhether the address belongs to the workspace, so its times are known.
busyobject[]RequiredstartstringRequired- Format
date-time endstringRequired- Format
date-time
suggestionsobject[]RequiredTimes everyone known is free, when
durationMinuteswas sent.startstringRequired- Format
date-time endstringRequired- Format
date-time
CalendarImportobject
objectstringRequired- One of
"calendar_import" idstringRequirediimp_followed by 24 hex characters.kindstringRequired- One of
"calendar" sourcestringRequiredfileis an upload. The others came with a mailbox import:takeoutfrom a Google Takeout archive,caldavandcarddavfrom the old provider,microsoftfrom an Outlook sign-in.One of"file""takeout""caldav""carddav""microsoft"statusstringRequiredundonemeans what it brought in was removed again.One of"uploading""queued""running""completed""failed""cancelled""undone"fileNamestringRequired- Can be null
fileBytesintegerRequired- At least 0
parentImportIdstringRequiredThe mailbox import it came with, when there was one.
Can be nullcountsobjectRequiredtotalintegerRequiredItems found so far.
At least 0importedintegerRequiredItems added.
At least 0mergedintegerRequiredContacts left as they were because the address book already holds them. Always 0 on a calendar import, where an event that is already here is counted under
skipped.At least 0skippedintegerRequiredItems left out for a reason given in
report.At least 0failedintegerRequired- At least 0
reportobjectRequiredcollectionsobject[]RequiredThe calendars or address books the items came from, by their original name.
namestringRequireditemsintegerRequired- At least 0
skippedRecord<string, integer>RequiredHow many items were left out, by reason.
samplesobject[]RequiredUp to 20 of the items left out.
namestringRequiredreasonstringRequired- One of
"uid-taken""no-start""duplicate""limit""invalid""empty"
lastErrorstringRequired- Can be null
undoablebooleanRequiredWhether the undo call would remove anything.
createdAtstringRequired- Format
date-time startedAtstringRequired- Can be nullFormat
date-time finishedAtstringRequired- Can be nullFormat
date-time undoneAtstringRequired- Can be nullFormat
date-time
CalendarImportListobject
objectstring- One of
"list" dataCalendarImport[]hasMorebooleanTrue when another page follows. Pass
nextCursorback ascursorto read it.nextCursorstringAn opaque cursor for the next page, or null on the last page. Pass it back unchanged.
Can be null
CalendarOccurrenceobject
objectstringRequired- One of
"calendar_occurrence" eventIdstringRequireduidstringRequiredThe iCalendar UID every copy of the event shares.
startstringRequired- Format
date-time endstringRequired- Format
date-time allDaybooleanRequiredsummarystringRequired- Can be null
locationstringRequired- Can be null
meetingUrlstringThe link to the video call, when it has one.
Can be nullstatusstringRequiredCONFIRMED,TENTATIVEorCANCELLED.transparencystringRequiredisOrganizerbooleanRequiredWhether you organise it, and so may change it.
organizerEmailstringRequired- Can be null
recurringbooleanRequiredWhether this is one occurrence of a repeating event.
myPartstatstringRequiredYour answer to the invitation, when you were invited.
Can be nullattendeeCountintegerRequired- At least 0
subscriptionIdstringThe calendar subscription it comes from, or null for your own calendar.
Can be null
CalendarOccurrenceListobject
objectstring- One of
"list" hasMorebooleanTrue when another page follows. Pass
nextCursorback ascursorto read it.nextCursorstringAn opaque cursor for the next page, or null on the last page. Pass it back unchanged.
Can be null
CalendarSubscriptionobject
objectstringRequired- One of
"calendar_subscription" idstringRequirednamestringRequiredurlstringRequiredThe https address it is read from.
colorstringRequired- One of
"blue""sky""teal""green""lime""yellow""orange""red""pink""purple""gray" statusstringRequiredactive,failingwhile reads fail and are retried, orstoppedafter ten failures in a row until you refresh it.One of"active""failing""stopped"lastErrorstringRequiredWhy the last read failed, if it did.
Can be nullOne of"unreachable""too-large""not-a-calendar""too-many-events"eventCountintegerRequired- At least 0
lastSyncedAtstringRequired- Can be nullFormat
date-time lastFetchedAtstringRequired- Can be nullFormat
date-time createdAtstringRequired- Format
date-time
CalendarSubscriptionListobject
objectstring- One of
"list"
DeletedCalendarEventobject
objectstringRequired- One of
"calendar_event" idstringRequireddeletedbooleanRequired- One of
true
DeletedCalendarFeedobject
objectstringRequired- One of
"calendar_feed" idstringRequireddeletedbooleanRequired- One of
true
DeletedCalendarSubscriptionobject
objectstringRequired- One of
"calendar_subscription" idstringRequireddeletedbooleanRequired- One of
true
Google Workspace
Fastmail