Calendar
Events, invitations, calendar links and subscriptions.
Calendar tools
| Tool | What it does |
|---|---|
| listCalendarEvents | Your occurrences between two moments, a repeating event once for each time it happens, with its place, status and your answer. The owner adds the team with includeTeam. |
| getCalendarEvent | One event in full, by id or by the threadId of the conversation that carries its invitation: the attendees and their answers, how it repeats and its reminders. |
| createCalendarEvent | Put an event on the calendar and invite the attendees from an address you may send as. In the app’s chat it asks first unless you asked for it. |
| updateCalendarEvent | Change an event you organise, and send the update to everyone invited. In the app’s chat it asks first unless you asked for it. |
| cancelCalendarEvent | Call off a meeting you organise and tell everyone invited. In the app’s chat it always asks first. |
| deleteCalendarEvent | Take an event off the calendar without telling anybody. In the app’s chat it always asks first. |
| respondToCalendarEvent | Accept, decline or tentatively accept an invitation, or propose a new time with your answer, and tell the organiser. In the app’s chat it asks first unless you asked for it. |
| declineCalendarProposal | Keep the original time of a meeting you organise after a guest proposed another one, and tell the guest. In the app’s chat it asks first unless you asked for it. |
| listCalendarFeeds | The secret links that publish your calendar to Google Calendar, Outlook or Apple Calendar, with their addresses. |
| createCalendarFeed | Make a secret link that publishes your calendar, with every detail or busy times only. In the app’s chat it always asks first. |
| resetCalendarFeed | Give a calendar link a new address, so the old one stops working. In the app’s chat it always asks first. |
| deleteCalendarFeed | Turn a calendar link off for good. In the app’s chat it always asks first. |
| listCalendarSubscriptions | The other calendars you subscribe to by link, and whether each is read without errors. |
| subscribeToCalendar | Add another calendar by its iCalendar link, such as a Google or Outlook calendar address, so its events show read-only. In the app’s chat it always asks first. |
| updateCalendarSubscription | Rename a calendar subscription or change its colour. In the app’s chat it asks first unless you asked for it. |
| refreshCalendarSubscription | Read a subscribed calendar again now, and restart one that stopped after failures. |
| unsubscribeFromCalendar | Remove a calendar subscription and the events it brought. In the app’s chat it always asks first. |
| listCalendarImports | The calendar files and calendars brought in, newest first, with how many events each added, found already here and left out. |
| getCalendarImport | One calendar import with its report: the calendars it read and what it left out, and why. |
| undoCalendarImport | Remove every event one calendar import added. Nobody is told. In the app’s chat it always asks first. |
| hideCalendarEvent | Hide an event from your own calendar and leave it for everyone else, or show it again. In the app’s chat it asks first unless you asked for it. |
| findMeetingTime | When people of the workspace are busy, and the first times everyone is free for a meeting of the length you give. |
Reading needs calendar:read and every change needs calendar:write. Anything that emails somebody also needs emails:send: inviting, updating or cancelling a meeting with attendees, every answer to an invitation, and declining a proposed time.
A client limited to some addresses sees and changes only the events one of them organises or attends, and sends only from them. It cannot manage calendar links or subscriptions, which cover the whole calendar of the person it acts for.
An event that came in through a calendar import emails nobody by default. updateCalendarEvent tells its guests only with sendInvites true, and cancelCalendarEvent and respondToCalendarEvent only with notifyGuests true. No tool uploads a calendar file: upload an .ics file in the Calendars dialog of the app or with POST /calendar/imports, then read or undo the import here.
For a repeating event, updateCalendarEvent, cancelCalendarEvent and deleteCalendarEvent take scope with occurrenceStart: occurrence reaches one date, following that date and every one after it, and series all of them. findMeetingTime refuses a client limited to some addresses, since it reads whole calendars.
listCalendarEvents takes q, words that every event it returns holds in its title, its place or its organiser, so a window of up to a year finds an event by name.
Reference
listCalendarEvents
The calendar between two moments, as the Calendar page of the app shows it: every occurrence in the window, a repeating event once for each time it happens, sorted by start, with its event id, place, status and your answer. from and to are ISO 8601 with a zone, at most a year apart, and timezone (an IANA zone, UTC unless you say) decides what an all-day event means. When more follow, the last line gives the offset to pass back. It lists your own events: the ones you made and the ones an address of yours organises or attends. For the workspace owner, includeTeam: true adds the rest of the workspace, apart from events somebody marked private. q keeps the events whose title, place or organiser holds every word, so pass a window of up to a year with it to find an event by name.
Inputs
fromstringRequired- Format
date-time tostringRequired- Format
date-time timezonestring- 1 to 64 characters
includeTeambooleanqstringWords 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 characterslimitinteger- At least 1At most 200
offsetinteger- At least 0
Also available in
- API
GET /calendar/events- 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
getCalendarEvent
One calendar event in full: when it is, where, who organised it, every attendee and their answer, your own answer, how it repeats and its reminders. Pass id for an event from listCalendarEvents, or threadId for the invitation a conversation carries.
Inputs
idstring- 1 to 64 characters
threadIdstring- 1 to 256 characters
Also available in
- API
GET /calendar/events/{id}GET /threads/{id}/event- TypeScript
nextmail.calendar.getEvent()nextmail.threads.getEvent()- Python
calendar.get_event()threads.get_event()- Ruby
calendar.get_eventthreads.get_event- PHP
calendar->getEventthreads->getEvent- Go
Calendar.GetEventThreads.GetEvent- Java
calendar().getEventthreads().getEvent- C#
Calendar.GetEventAsyncThreads.GetEventAsync
createCalendarEvent
Put an event on the calendar, as New event on the Calendar page does. start and end are ISO 8601 with a zone. With attendees, an invitation goes to each of them from the address in from, which has to be one you may send as, unless sendInvites is false. reminders takes minutes before the start, and recurrence an RRULE such as FREQ=WEEKLY;BYDAY=MO.
Inputs
summarystringRequired- 1 to 255 characters
startstringRequired- Format
date-time endstringRequired- Format
date-time descriptionstring- Up to 8000 characters
locationstring- Up to 255 characters
urlstring- Up to 2000 charactersFormat
uri meetingUrlstringA 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 charactersallDaybooleantimezonestring- 1 to 64 characters
recurrencestring- Up to 512 characters
attendeesobject[]- Up to 200 items
emailstringRequired- Up to 320 charactersFormat
email namestring- Up to 128 characters
optionalboolean
remindersobject[]- Up to 5 items
minutesBeforeintegerRequired- At least 0At most 40320
actionstringDISPLAY, the default, shows a reminder; EMAIL sends one; AUDIO plays a sound.
One of"DISPLAY""EMAIL""AUDIO"
transparencystringOPAQUE, the default, shows the time as busy; TRANSPARENT leaves it free.
One of"OPAQUE""TRANSPARENT"visibilitystringPUBLIC, PRIVATE or CONFIDENTIAL: how much a calendar shared with others shows of it.
One of"PUBLIC""PRIVATE""CONFIDENTIAL"sendInvitesbooleanfromstring- Up to 320 characters
Also available in
updateCalendarEvent
Change an event you organise: its title, time, place, video call link, attendees, reminders or repeating. A field left out keeps its value, and attendees replaces the whole list. Everyone invited gets the updated invitation unless sendInvites is false. An event that came in through a calendar import tells nobody unless sendInvites is true. For a repeating event, scope occurrence with occurrenceStart changes one date, following changes that date and the ones after it, and series changes them all.
Inputs
idstringRequired- 1 to 64 characters
summarystring- 1 to 255 characters
startstring- Format
date-time endstring- Format
date-time descriptionstring- Up to 8000 characters
locationstring- Up to 255 characters
urlstring- Up to 2000 charactersFormat
uri meetingUrlstringA 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 charactersallDaybooleantimezonestring- 1 to 64 characters
recurrencestring- Up to 512 characters
attendeesobject[]- Up to 200 items
emailstringRequired- Up to 320 charactersFormat
email namestring- Up to 128 characters
optionalboolean
remindersobject[]- Up to 5 items
minutesBeforeintegerRequired- At least 0At most 40320
actionstringDISPLAY, the default, shows a reminder; EMAIL sends one; AUDIO plays a sound.
One of"DISPLAY""EMAIL""AUDIO"
transparencystringOPAQUE, the default, shows the time as busy; TRANSPARENT leaves it free.
One of"OPAQUE""TRANSPARENT"visibilitystringPUBLIC, PRIVATE or CONFIDENTIAL: how much a calendar shared with others shows of it.
One of"PUBLIC""PRIVATE""CONFIDENTIAL"sendInvitesbooleanfromstring- Up to 320 characters
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
Also available in
cancelCalendarEvent
Call off a meeting you organise, as Cancel meeting does in the app: it stays on the calendar marked cancelled, and everyone invited is told it is off, from the address in from. An event that came in through a calendar import tells nobody unless notifyGuests is true, and notifyGuests false keeps any cancellation quiet. For a repeating meeting, scope occurrence with occurrenceStart calls off one date, and following that date and the ones after it. A chat always asks first.
Inputs
idstringRequired- 1 to 64 characters
fromstring- Up to 320 characters
notifyGuestsbooleanscopestringWhich 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
Also available in
deleteCalendarEvent
Remove an event from the calendar for good, as Remove does in the app. Nobody else is told, so call off a meeting with others in it with cancelCalendarEvent instead. For a repeating event, scope occurrence with occurrenceStart removes one date, and following that date and the ones after it. A chat always asks first.
Inputs
idstringRequired- 1 to 64 characters
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
Also available in
respondToCalendarEvent
Answer an invitation: ACCEPTED, DECLINED or TENTATIVE. The answer goes to the organiser by email from the invited address you may send as, or from respondingAs when the invitation went to more than one of yours. On an event that came in through a calendar import the answer is only recorded, and the organiser is told when notifyGuests is true.
Inputs
idstringRequired- 1 to 64 characters
responsestringRequired- One of
"ACCEPTED""DECLINED""TENTATIVE" respondingAsstring- Up to 320 characters
notifyGuestsbooleanproposedStartstring- Format
date-time proposedEndstring- Format
date-time
Also available in
declineCalendarProposal
Keep the original time of a meeting you organise after a guest proposed another one. The guest is told by email. To take the proposed time instead, change the event with updateCalendarEvent. A chat asks first unless you asked for it.
Inputs
idstringRequired- 1 to 64 characters
attendeestringRequired- Up to 320 charactersFormat
email fromstring- Up to 320 characters
Also available in
listCalendarFeeds
List the secret links that publish your calendar to other calendar apps such as Google Calendar, Outlook or Apple Calendar: full details or busy times only.
Inputs
Takes no input.
Also available in
createCalendarFeed
Make a secret link that publishes your calendar, to paste into Google Calendar (From URL), Outlook (Subscribe from web) or Apple Calendar. mode full shows every detail, busy only the times you are busy. Anyone with the link can read it. A chat always asks first.
Inputs
namestringRequired- 1 to 100 characters
modestringRequired- One of
"full""busy"
Also available in
resetCalendarFeed
Replace the secret in a calendar link, so the old address stops working everywhere it was shared. A chat always asks first.
Inputs
idstringRequired- 1 to 64 characters
Also available in
deleteCalendarFeed
Turn a calendar link off for good. Calendar apps subscribed to it stop getting updates. A chat always asks first.
Inputs
idstringRequired- 1 to 64 characters
Also available in
listCalendarSubscriptions
List the other calendars you subscribe to by link, such as a Google or Outlook calendar, a team rota or public holidays, with whether each is read without errors.
Inputs
Takes no input.
Also available in
subscribeToCalendar
Add another calendar by its iCalendar link (https, http or webcal), such as the secret address of a Google calendar or a published Outlook calendar. Its events show on your calendar, read-only, and are read again about every half hour. A chat always asks first.
Inputs
urlstringRequired- 1 to 2048 characters
namestring- 1 to 100 characters
colorstring- One of
"blue""sky""teal""green""lime""yellow""orange""red""pink""purple""gray"
Also available in
updateCalendarSubscription
Rename a calendar subscription or give it another colour.
Inputs
idstringRequired- 1 to 64 characters
namestring- 1 to 100 characters
colorstring- One of
"blue""sky""teal""green""lime""yellow""orange""red""pink""purple""gray"
Also available in
refreshCalendarSubscription
Read a subscribed calendar again now, and restart one that stopped after failures.
Inputs
idstringRequired- 1 to 64 characters
Also available in
unsubscribeFromCalendar
Remove a calendar subscription and every event it brought onto your calendar. A chat always asks first.
Inputs
idstringRequired- 1 to 64 characters
Also available in
listCalendarImports
The calendar imports of this workspace, newest first, as Import in the Calendars dialog of the app lists them: an .ics file somebody uploaded, the calendars inside a Google Takeout archive, or the calendars pulled from an old mailbox. Each line says how many events it found, added, found already here and left out. A member sees their own. Uploading a file takes bytes a tool call does not carry, so that is done in the app, over the REST API or with the CLI. One page at a time: when more follow, the last line gives a cursor to pass back for the next page.
Inputs
limitinteger- At least 1At most 100
cursorstring
Also available in
- API
GET /calendar/imports- 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
getCalendarImport
One calendar import by its id, with its report: the calendars the file held and how many events each gave, how many were left out and why, and the first few that were not brought in. Imported events are ordinary events, and nobody invited to one was sent anything.
Inputs
idstringRequired- 1 to 64 characters
Also available in
undoCalendarImport
Remove every event one calendar import added, as Remove imported events does in the app. Events that were on the calendar before it stay, and nobody is told. It cannot be taken back, though the same file can be imported again. A chat always asks first.
Inputs
idstringRequired- 1 to 64 characters
Also available in
hideCalendarEvent
Hide an event from your own calendar and leave it for everyone else, as Hide from my calendar does in the app, or put it back with hidden false. Use it for an invitation that reached you through a shared address, or an event you may not remove. Hiding also stops its reminders for you. A chat asks first unless you asked for it.
Inputs
idstringRequired- 1 to 64 characters
hiddenbooleanfalse shows a hidden event again.
Also available in
- API
POST /calendar/events/{id}/hidePOST /calendar/events/{id}/unhide- TypeScript
nextmail.calendar.hideEvent()nextmail.calendar.unhideEvent()- Python
calendar.hide_event()calendar.unhide_event()- Ruby
calendar.hide_eventcalendar.unhide_event- PHP
calendar->hideEventcalendar->unhideEvent- Go
Calendar.HideEventCalendar.UnhideEvent- Java
calendar().hideEventcalendar().unhideEvent- C#
Calendar.HideEventAsyncCalendar.UnhideEventAsync
findMeetingTime
When people are busy and the first times everyone is free, as Find a time in the event editor shows it. emails takes up to 20 addresses: one of the workspace shows the busy times of the person who holds it, and any other address is unknown. from and to are ISO 8601 with a zone, at most 31 days apart. With durationMinutes it suggests up to five times, on weekdays between 09:00 and 17:00 in timezone (UTC unless you say).
Inputs
emailsstring[]Required- 1 to 20 items
fromstringRequired- Format
date-time tostringRequired- Format
date-time timezonestring- 1 to 64 characters
durationMinutesinteger- At least 5At most 480
Google Workspace
Fastmail