client.calendar
Every method in this namespace: its signature, its parameters, what it returns and an example.
Methods
Calendar events found in mail, expanded into occurrences.
calendar.list_events
List one page of event occurrences inside a time window
list_events(from:, to:, timezone: nil, include_team: nil, q: nil, limit: nil, cursor: nil, api_key: nil) -> Nextmail::PageExpands your events into their occurrences between from and to and returns one page of them, sorted by start time and then by event id. A recurring series gives one row per instance in the window, with its excluded dates left out, and every row points back to its event through eventId. The window is required because a repeating series has no end to list up to. Follow next_cursor while has_more? is true, with the same from:, to: and timezone:, to read every occurrence, or let list_all_events and iterate_events do that walk.
to must be after from and at most 366 days later. A missing from or to is a 422 invalid_parameter, while a value that does not parse, a reversed or overlong window, or an unknown zone is a 400 invalid_parameter naming the field. Both bounds take a Time, DateTime, Date or ISO 8601 String, and the SDK sends a Time or DateTime as a UTC ISO 8601 instant.
timezone is an IANA zone and defaults to UTC on the server. It is used to expand any event stored without a zone of its own, which is what decides the day an all day event lands on.
Parameters
fromTime, DateTime, Date or StringRequiredStart of the window.
toTime, DateTime, Date or StringRequiredEnd of the window, after
fromand at most 366 days later.timezoneStringIANA zone such as
Europe/London, at most 64 characters. Defaults toUTC.include_teamBooleantrueadds the events of the rest of the workspace, apart from the ones marked private. Only a key of the workspace owner sees more with it. Defaults tofalse.qStringWords to look for in the title, the place and the organiser, at most 200 characters. Only events that hold every word come back, so pass a long window to find an event by name.
limitIntegerOccurrences per page, a whole number from 1 to 100. The server defaults to 25.
cursorStringThe
next_cursorof the previous page, sent with the same window. It is opaque, so never build one yourself.api_keyStringOverrides the client's API key for this call only.
Returns
An Nextmail::Page of occurrence Hashes, with items, has_more? and next_cursor. Each item has eventId, uid, start, end, allDay, summary, location, status, transparency, isOrganizer, organizerEmail, recurring, myPartstat and attendeeCount.
Example
from = Time.nowto = from + 7 * 24 * 60 * 60 page = client.calendar.list_events(from:, to:, timezone: "Europe/London", limit: 50) page.items.each do |occurrence| puts "#{occurrence[:start]} #{occurrence[:summary]} #{occurrence[:myPartstat] || "not invited"}"end p page.has_more?, page.next_cursorNotes
The list holds 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, and
include_team: trueadds the rest of the workspace, apart from events somebody marked private. A member's app and a narrowed key always get their own view.myPartstatis the response recorded for one of your own addresses, or for the addresses a narrowed key covers, and nil when none of them is an attendee.A narrowed key only sees occurrences whose organiser is one of the addresses it covers or where one of them is an attendee.
Cancelled events are not filtered out. Check
statusforCANCELLED.Nothing in the window is dropped. A series repeats at most once a day, so one series gives at most one row per day of the window, and every one of them is reachable through the pages.
The cursor holds the start time and event id of the last row, so an event deleted or moved between pages never breaks the walk. A cursor this list did not hand out is a 400
invalid_cursor.
Also available in
calendar.list_all_events
Collect every occurrence inside a time window into one array
list_all_events(from:, to:, timezone: nil, include_team: nil, q: nil, limit: nil, cursor: nil, api_key: nil) -> Array<Hash>Walks every page of list_events for one window and returns all of its occurrences, sorted by start time and then by event id. It follows next_cursor until has_more? is false, sending the same from:, to: and timezone: with each request.
A window of up to 366 days of a busy calendar can hold thousands of occurrences, so prefer iterate_events when you can stop early.
Parameters
fromTime, DateTime, Date or StringRequiredStart of the window.
toTime, DateTime, Date or StringRequiredEnd of the window, after
fromand at most 366 days later.timezoneStringIANA zone such as
Europe/London, at most 64 characters. Defaults toUTC.include_teamBooleantrueadds the events of the rest of the workspace, apart from the ones marked private. Only a key of the workspace owner sees more with it. Defaults tofalse.qStringWords to look for in the title, the place and the organiser, at most 200 characters. Only events that hold every word come back, so pass a long window to find an event by name.
limitIntegerPage size for each request, 1 to 100. The server defaults to 25.
cursorStringStarts the walk from this cursor instead of the start of the window.
api_keyStringOverrides the client API key for every page of this walk.
Returns
An Array of occurrence Hashes holding every occurrence in the window, earliest first.
Example
occurrences = client.calendar.list_all_events( from: "2026-10-01T00:00:00Z", to: "2026-11-01T00:00:00Z", limit: 100) busy = occurrences.select { |occurrence| occurrence[:transparency] == "OPAQUE" } puts "#{busy.length} busy blocks in October"Notes
If any page fails the call raises, and the occurrences already fetched are discarded.
Also available in
calendar.iterate_events
Stream the occurrences inside a time window one at a time
iterate_events(from:, to:, timezone: nil, include_team: nil, q: nil, limit: nil, cursor: nil, api_key: nil, &block) -> Enumerator<Hash>Returns an Enumerator over the occurrences in one window that yields them individually, earliest first, or yields each one to a block when given one, and fetches the next page only when the current one is drained. Without a block nothing is requested until you consume it, and breaking out of the loop stops further requests, which makes it the way to find the next free slot or the next meeting without reading the whole window.
The walk ends when has_more? is false, when a page carries no next_cursor, or when the server repeats a cursor.
Parameters
fromTime, DateTime, Date or StringRequiredStart of the window.
toTime, DateTime, Date or StringRequiredEnd of the window, after
fromand at most 366 days later.timezoneStringIANA zone such as
Europe/London, at most 64 characters. Defaults toUTC.include_teamBooleantrueadds the events of the rest of the workspace, apart from the ones marked private. Only a key of the workspace owner sees more with it. Defaults tofalse.qStringWords to look for in the title, the place and the organiser, at most 200 characters. Only events that hold every word come back, so pass a long window to find an event by name.
limitIntegerPage size per request, 1 to 100. The server defaults to 25.
cursorStringStarts the walk from this cursor instead of the start of the window.
api_keyStringOverrides the client API key for every page of this walk.
Returns
An Enumerator of occurrence Hashes (or yields each one to a block), one occurrence per step.
Example
from = Time.nowto = from + 30 * 24 * 60 * 60 meeting = client.calendar.iterate_events(from:, to:).find { |occurrence| occurrence[:myPartstat] } puts "next meeting #{meeting[:start]} #{meeting[:summary]}" if meetingNotes
A page request that fails raises out of the loop, after every occurrence of the pages before it has been yielded.
Also available in
calendar.get_event
Read an event with its attendees
get_event(id, api_key: nil) -> HashReturns a stored event with its attendees and their responses. What the server understood from the iCalendar data is structured here: recurrence holds the RRULE text, exdates the excluded instances, organizer the organiser and alarms the reminders, each a Hash with minutesBefore and action. The raw iCalendar source is not included, and get_event_ics serves the event as a document.
id is the event id, the eventId on an occurrence, and not the iCalendar uid. A recurring series is one event however many occurrences it has, so start and end describe its first instance. messageId and threadId link the event to mail in the mailbox when there is any.
Attendees come back in the order they were added, each with partstat, role, rsvp, cutype and respondedAt. A narrowed key gets a 404 unless one of the addresses it covers organises the event or is on the attendee list, and a key that holds a whole domain covers every address on it.
Parameters
idStringRequiredEvent id, the
eventIdof an occurrence, such ascal_followed by 24 hex characters.api_keyStringOverrides the client's API key for this call only.
Returns
A Hash with id, uid, sequence, summary, description, location, url, start, end, allDay, timezone, recurrence, exdates, status, transparency, visibility, organizer, isOrganizer, source, messageId, threadId, alarms, attendees, createdAt and updatedAt.
Example
event = client.calendar.get_event("cal_3f9a1c7e5b2d48a06c1e9f4b") puts event[:summary], event[:recurrence] || "one off"p event[:attendees].map { |attendee| "#{attendee[:email]}: #{attendee[:partstat]}" }Notes
status,transparencyandvisibilitycarry iCalendar values, and default toCONFIRMED,OPAQUEandPUBLIC.An attendee's
partstatdefaults toNEEDS-ACTIONandroletoREQ-PARTICIPANTuntil a response is recorded.
Also available in
calendar.get_event_ics
Download an event as an iCalendar document
get_event_ics(id, api_key: nil) -> StringReturns the event serialised as an .ics document, as a raw String rather than a parsed Hash. The server sends it as text/calendar; charset=utf-8 with a download filename built from the event's uid, and the SDK requests that type and returns the body as a UTF-8 String without parsing it.
The document declares METHOD:PUBLISH, and the content type carries no method parameter. That is deliberate: a REQUEST document makes a calendar client offer accept and decline and reply to the organiser, and this endpoint has no authority to invite anyone. Import it to show what the event currently is, not to send an invitation.
It holds one VEVENT with the attendees and their participation status, the recurrence rule, excluded dates and alarms. Lines end in CRLF and long lines are folded. DTSTAMP is the time of the request, so two downloads of an unchanged event differ on that line.
Parameters
idStringRequiredEvent id, the
eventIdof an occurrence.api_keyStringOverrides the client's API key for this call only.
Returns
A String, the iCalendar text from BEGIN:VCALENDAR to END:VCALENDAR.
Example
ics = client.calendar.get_event_ics("cal_8d3f0a2b9c4e41f7a6b5c2d1")summary = ics.split("\r\n").find { |line| line.start_with?("SUMMARY:") } puts summaryNotes
Errors still come back as JSON and raise
Nextmail::ApiError, so a failure never comes back as a String.Timed events are written in the zone they were created in, as local times with a
TZIDand aVTIMEZONEthat carries the rules of that zone, and all day events asDATEvalues.A narrowed key gets a 404 on the same terms as
get_event.
Also available in
calendar.create_event
Put an event on the calendar
create_event(body = nil, api_key: nil, **fields) -> HashCreates an event, as New event on the Calendar page of the app does. start and end take a Time or ISO 8601 with a zone, and the SDK sends a Time as a UTC instant. timezone is the IANA zone the event belongs to, which decides what an all-day event means.
With attendees, an invitation goes to each of them by email from from, which has to be an address the key may send as, so the call also needs emails:send. Send sendInvites: false to keep it to your own calendar.
Parameters
summaryStringRequiredThe title, 1 to 255 characters.
startTime, DateTime, Date or StringRequiredWhen it starts, a
Timeor ISO 8601 with a zone.endTime, DateTime, Date or StringRequiredWhen it ends, after
startand at most two years later.descriptionStringNotes about the event, up to 8,000 characters.
locationStringWhere it is: a room, an address or a link.
urlStringA link that belongs to the event.
meetingUrlStringThe link to the video call, such as a Zoom, Meet or Teams address. The invitation carries it, so guests get a Join button in their calendar too.
allDayBooleanWhether it fills whole days.
startandendthen mark the days.timezoneStringThe IANA zone the event belongs to,
UTCunless you say.recurrenceStringAn RRULE such as
FREQ=WEEKLY;BYDAY=MOwhen it repeats.attendeesArray<Hash>Up to 200 people to invite, each a Hash with
emailand, if you like,nameandoptional.remindersArray<Hash>Up to five reminders, each a Hash with
minutesBeforeand, if you like,action.transparencyStringOPAQUEshows you busy andTRANSPARENTfree.visibilityStringPUBLIC,PRIVATEorCONFIDENTIAL.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.
api_keyStringOverrides the client's API key for this call only.
Returns
A Hash for the new event, shaped like the one get_event returns, with its attendees and their responses.
Example
event = client.calendar.create_event( summary: "Planning", start: Time.utc(2026, 10, 12, 9, 0), end: Time.utc(2026, 10, 12, 9, 30), attendees: [{email: "[email protected]"}], from: "[email protected]") puts event[:id], event[:attendees].lengthNotes
The SDK does not retry it, because a second call makes a second event and invites everybody again.
A key that may not send as
fromis refused with 403from_address_forbidden, and an event with attendees and nofromwith 422invalid_parameter. Invitations withoutemails:sendare a 403insufficient_scope.
Also available in
calendar.update_event
Change an event
update_event(id, patch = nil, api_key: nil, **fields) -> HashChanges an event you organise. A field you leave out keeps its value, and attendees replaces the whole list. Everyone invited gets the updated invitation by email from from, so a change to an event with attendees needs emails:send too, unless sendInvites is false.
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, and series all of them. With following the later dates become a new series with its own id, which is what comes back, and the old one ends the day before.
Parameters
idStringRequiredEvent id, the
eventIdof an occurrence, such ascal_followed by 24 hex characters.summaryStringThe title, 1 to 255 characters.
startTime, DateTime, Date or StringWhen it starts, a
Timeor ISO 8601 with a zone.endTime, DateTime, Date or StringWhen it ends, after
startand at most two years later.descriptionStringNotes about the event, up to 8,000 characters.
locationStringWhere it is: a room, an address or a link.
urlStringA link that belongs to the event.
meetingUrlStringThe link to the video call. An empty string takes it off.
allDayBooleanWhether it fills whole days.
startandendthen mark the days.timezoneStringThe IANA zone the event belongs to,
UTCunless you say.recurrenceStringAn RRULE such as
FREQ=WEEKLY;BYDAY=MOwhen it repeats.attendeesArray<Hash>Up to 200 people to invite, each a Hash with
emailand, if you like,nameandoptional. It replaces the whole list.remindersArray<Hash>Up to five reminders, each a Hash with
minutesBeforeand, if you like,action.transparencyStringOPAQUEshows you busy andTRANSPARENTfree.visibilityStringPUBLIC,PRIVATEorCONFIDENTIAL.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.
scopeStringoccurrence,followingorseries: which dates of a repeating event change. Left out, the change reaches the event or date the id names.occurrenceStartTime, DateTime, Date or StringThe start of the date you mean, as
list_eventsgives it. Needed withoccurrenceandfollowing.api_keyStringOverrides the client's API key for this call only.
Returns
The event Hash as it stands after the change, shaped like the one get_event returns, with sequence one higher.
Example
event = client.calendar.update_event( "cal_3f9a1c7e5b2d48a06c1e9f4b", start: "2026-10-12T10:00:00Z", end: "2026-10-12T10:30:00Z") puts event[:start], event[:sequence]Notes
The SDK does not retry it, because a retry after a lost response sends the update to everybody again.
An event organised by somebody else is refused with 403
not_organizer: answer it withrespond_to_eventinstead. An event the key does not reach is a 404.
Also available in
calendar.delete_event
Remove an event from the calendar
delete_event(id, scope: nil, occurrence_start: nil, api_key: nil) -> HashRemoves an event for good, as Remove does in the app. Nobody else is told, so call off a meeting with others in it with cancel_event instead. For a repeating event, scope: occurrence with occurrence_start: removes one date, and following that date and every one after it.
Parameters
idStringRequiredEvent id, the
eventIdof an occurrence, such ascal_followed by 24 hex characters.scopeStringoccurrence,followingorseries: which dates of a repeating event go.occurrence_startTime, DateTime, Date or StringThe start of the date you mean, as
list_eventsgives it. Needed withoccurrenceandfollowing.api_keyStringOverrides the client's API key for this call only.
Returns
A Hash with object, id and deleted set to true.
Example
client.calendar.delete_event("cal_3f9a1c7e5b2d48a06c1e9f4b", scope: "occurrence", occurrence_start: "2026-10-19T09:00:00Z")Notes
An event organised by somebody else is refused with 403
not_organizer, and an event that is gone or that the key does not reach is a 404. An event you may not remove can still be taken off your own calendar withhide_event.
Also available in
calendar.cancel_event
Call off a meeting
cancel_event(id, body = nil, api_key: nil, **fields) -> HashCancels 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 by email from from, so a meeting with attendees also needs emails:send.
For a repeating meeting, scope occurrence with occurrenceStart calls off one date, and following that date and every one after it. Guests get the matching update.
Parameters
idStringRequiredEvent id, the
eventIdof an occurrence, such ascal_followed by 24 hex characters.fromStringThe address the cancellation comes from. It has to be one the key may send as.
scopeStringoccurrence,followingorseries: which dates of a repeating meeting are called off.occurrenceStartTime, DateTime, Date or StringThe start of the date you mean, as
list_eventsgives it. Needed withoccurrenceandfollowing.api_keyStringOverrides the client's API key for this call only.
Returns
The event Hash, shaped like the one get_event returns, with status set to CANCELLED.
Example
event = client.calendar.cancel_event("cal_3f9a1c7e5b2d48a06c1e9f4b", from: "[email protected]") puts event[:status]Notes
The SDK does not retry it, because a retry sends the cancellation again.
An event organised by somebody else is refused with 403
not_organizer.
Also available in
calendar.respond_to_event
Answer an invitation
respond_to_event(id, body = nil, api_key: nil, **fields) -> HashAccepts, declines or tentatively accepts an invitation, as the buttons of an invitation do in the app. The answer goes to the organiser by email from the invited address the key may send as, or from respondingAs when the invitation went to more than one of yours, so it needs emails:send as well.
Parameters
idStringRequiredEvent id, the
eventIdof an occurrence, such ascal_followed by 24 hex characters.responseStringRequiredACCEPTED,DECLINEDorTENTATIVE.respondingAsStringWhich of your invited addresses answers, when there is more than one.
proposedStartTime, DateTime, Date or StringA new start to propose with your answer, a
Timeor ISO 8601 with a zone, sent together withproposedEnd.proposedEndTime, DateTime, Date or StringThe end of the proposed time.
api_keyStringOverrides the client's API key for this call only.
Returns
The event Hash, shaped like the one get_event returns, with your answer on your attendee row.
Example
event = client.calendar.respond_to_event("cal_3f9a1c7e5b2d48a06c1e9f4b", response: "ACCEPTED") p event[:attendees].map { |attendee| "#{attendee[:email]}: #{attendee[:partstat]}" }Notes
An event that invited none of the addresses the key may send as is refused with 403
not_invited, and a cancelled meeting with 409event_cancelled.When the organiser cannot be reached, nothing changes and the call is a 409
reply_not_sent.With
proposedStartandproposedEndthe organiser gets a counter-proposal, as Propose a new time sends from Google Calendar and Outlook, and decides whether to move the meeting.
Also available in
calendar.decline_proposal
Decline a proposed time
decline_proposal(id, body = nil, api_key: nil, **fields) -> HashKeeps the original time of a meeting you organise after a guest proposed another one, as Keep the original does on the event in the app. The guest is told by email from from, or from the organising address, so it needs emails:send as well. To take the proposed time instead, change the event with update_event.
Parameters
idStringRequiredEvent id, the
eventIdof an occurrence, such ascal_followed by 24 hex characters.attendeeStringRequiredThe guest whose proposal you decline, by email address.
fromStringThe address the answer is sent from, when it is not the organising address.
api_keyStringOverrides the client's API key for this call only.
Returns
The event Hash, shaped like the one get_event returns, with the guest's proposedStart and proposedEnd cleared.
Example
event = client.calendar.decline_proposal("cal_3f9a1c7e5b2d48a06c1e9f4b", attendee: "[email protected]") puts "#{event[:summary]} keeps its time"Notes
A guest who has not proposed a new time is refused with 404
proposal_not_found, and an event somebody else organises with 403not_organizer.
Also available in
calendar.hide_event
Hide an event from your calendar
hide_event(id, api_key: nil) -> HashTakes an event off your own calendar and leaves it 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 an event you may not remove. It hides every date of a repeating event, and stops its reminders for you. unhide_event brings it back.
Parameters
idStringRequiredEvent id, the
eventIdof an occurrence, such ascal_followed by 24 hex characters.api_keyStringOverrides the client's API key for this call only.
Returns
A Hash with object, id, uid and hidden set to true.
Example
hidden = client.calendar.hide_event("cal_3f9a1c7e5b2d48a06c1e9f4b") puts hidden[:hidden]Notes
Hiding an event that is already hidden changes nothing, so it is safe to repeat. An event the key does not reach is a 404.
It hides the event for the person the key or app acts for, and nobody else.
list_eventsleaves it out from then on, andget_eventstill finds it, withhiddentrue.
Also available in
calendar.unhide_event
Show a hidden event again
unhide_event(id, api_key: nil) -> HashPuts an event you hid back on your calendar, as Show on my calendar does on the invitation in the app.
Parameters
idStringRequiredEvent id, the
eventIdof an occurrence, such ascal_followed by 24 hex characters.api_keyStringOverrides the client's API key for this call only.
Returns
A Hash with object, id, uid and hidden set to false.
Example
client.calendar.unhide_event("cal_3f9a1c7e5b2d48a06c1e9f4b")Notes
An event that was not hidden stays as it was, so it is safe to repeat.
Also available in
calendar.free_busy
Free and busy times
free_busy(emails:, from:, to:, timezone: nil, duration_minutes: nil, api_key: nil) -> HashWhen the people you name are busy, as Find a time in the event editor of the app shows it. An 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. Any other address comes back with known false.
With duration_minutes:, suggestions lists up to five times when everyone known is free, on weekdays between 09:00 and 17:00 in timezone:. from: and to: take a Time or an ISO 8601 string and may be at most 31 days apart.
Parameters
emailsArray<String>RequiredThe addresses to look up, at most 20.
fromTime, DateTime, Date or StringRequiredThe start of the window.
toTime, DateTime, Date or StringRequiredThe end of the window, at most 31 days after
from.timezoneStringThe IANA zone the suggested times keep to working hours in,
UTCunless you say.duration_minutesIntegerThe length of the meeting, 5 to 480 minutes. Send it to get
suggestions.api_keyStringOverrides the client's API key for this call only.
Returns
A Hash with people, each with email, known and busy, its busy times as Hashes with start and end, and suggestions in the same shape.
Example
times = client.calendar.free_busy( emails: ["[email protected]", "[email protected]"], from: Time.now, to: Time.now + (7 * 24 * 60 * 60), timezone: "Europe/London", duration_minutes: 30) times[:suggestions].each { |time| puts time[:start] }Notes
A key or an app limited to particular addresses or domains is refused with 422
capability_unsupported, because the answer reads whole calendars.It reads the calendars as they are now and holds nothing, so a suggested time can be gone a moment later.
Also available in
calendar.list_feeds
List calendar links
list_feeds(api_key: nil) -> Array<Hash>Returns the secret links that publish your calendar to other calendar apps, as the Share tab of the calendar settings in the app lists them. Anyone with a link can read what it shows, so treat url and webcalUrl like passwords.
Parameters
api_keyStringOverrides the client's API key for this call only.
Returns
An Array of Hashes, each with id, name, mode, url, webcalUrl and when calendar apps last read it.
Example
client.calendar.list_feeds.each do |feed| puts "#{feed[:name]} (#{feed[:mode]}): #{feed[:url]}"endNotes
A key limited to particular addresses or domains is refused with 422
capability_unsupported, because a link covers the whole calendar.
Also available in
calendar.create_feed
Create a calendar link
create_feed(body = nil, api_key: nil, **fields) -> HashMakes 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 reads the link again on its own schedule, usually every few hours.
Parameters
nameStringRequiredThe name calendar apps show for the calendar, up to 100 characters.
modeStringRequiredfullfor every detail,busyfor busy times only.api_keyStringOverrides the client's API key for this call only.
Returns
The link Hash with the new url and webcalUrl.
Example
feed = client.calendar.create_feed(name: "Work (busy)", mode: "busy") puts "Paste into Google Calendar: #{feed[:url]}"Notes
One person may keep 10 links. One more is refused with 409
calendar_feed_limit.
Also available in
calendar.reset_feed
Reset a calendar link
reset_feed(id, api_key: nil) -> HashReplaces 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.
Parameters
idStringRequiredCalendar link id,
cfd_followed by 24 hex characters.api_keyStringOverrides the client's API key for this call only.
Returns
The link Hash with its new url and webcalUrl.
Example
feed = client.calendar.reset_feed("cfd_3f9a1c7e5b2d48a06c1e9f4b") puts feed[:url]Notes
A link that is not yours is a 404
calendar_feed_not_found.
Also available in
calendar.delete_feed
Delete a calendar link
delete_feed(id, api_key: nil) -> HashTurns a calendar link off for good. Calendar apps that subscribed to it stop getting updates.
Parameters
idStringRequiredCalendar link id,
cfd_followed by 24 hex characters.api_keyStringOverrides the client's API key for this call only.
Returns
A Hash with object, id and deleted set to true.
Example
client.calendar.delete_feed("cfd_3f9a1c7e5b2d48a06c1e9f4b")Notes
A link that is not yours is a 404
calendar_feed_not_found.
Also available in
calendar.list_subscriptions
List calendar subscriptions
list_subscriptions(api_key: nil) -> Array<Hash>Returns 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.
Parameters
api_keyStringOverrides the client's API key for this call only.
Returns
An Array of Hashes, each with name, url, color, status, lastError and how many events it holds.
Example
client.calendar.list_subscriptions.each do |subscription| puts "#{subscription[:name]}: #{subscription[:status]}, #{subscription[:eventCount]} events"endNotes
statusisfailingwhile reads fail and are retried, andstoppedafter ten failures in a row until you refresh it.
Also available in
calendar.create_subscription
Subscribe to a calendar
create_subscription(body = nil, api_key: nil, **fields) -> HashAdds 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.
Parameters
urlStringRequiredThe calendar link,
https,httporwebcal.nameStringThe name to show, up to 100 characters.
colorStringThe colour of its events, from
Nextmail::CALENDAR_COLORS.api_keyStringOverrides the client's API key for this call only.
Returns
The subscription Hash with its first events read.
Example
holidays = client.calendar.create_subscription(url: "webcal://example.com/holidays.ics", color: "green") puts "#{holidays[:name]}: #{holidays[:eventCount]} events"Notes
An address that does not answer with a calendar is refused with 422
calendar_subscription_unreadable, and one you already subscribe to with 409calendar_subscription_exists.One person may subscribe to 20 calendars.
Also available in
calendar.update_subscription
Change a calendar subscription
update_subscription(id, patch = nil, api_key: nil, **fields) -> HashRenames a subscription or gives it another colour.
Parameters
idStringRequiredSubscription id,
csb_followed by 24 hex characters.nameStringThe new name, up to 100 characters.
colorStringThe new colour, from
Nextmail::CALENDAR_COLORS.api_keyStringOverrides the client's API key for this call only.
Returns
The subscription Hash as it stands now.
Example
client.calendar.update_subscription("csb_3f9a1c7e5b2d48a06c1e9f4b", name: "Team rota", color: "purple")Notes
A subscription that is not yours is a 404
calendar_subscription_not_found.
Also available in
calendar.refresh_subscription
Refresh a calendar subscription
refresh_subscription(id, api_key: nil) -> HashReads a subscribed calendar again now instead of waiting for the next half-hourly read, and restarts one that stopped after repeated failures.
Parameters
idStringRequiredSubscription id,
csb_followed by 24 hex characters.api_keyStringOverrides the client's API key for this call only.
Returns
The subscription Hash after the read, with status and lastError.
Example
subscription = client.calendar.refresh_subscription("csb_3f9a1c7e5b2d48a06c1e9f4b") puts "Could not read it: #{subscription[:lastError]}" if subscription[:lastError]Notes
A calendar read less than a minute ago is refused with 429
calendar_subscription_refresh_too_soon.
Also available in
- API
POST /calendar/subscriptions/{id}/refresh- TypeScript
nextmail.calendar.refreshSubscription()- Python
calendar.refresh_subscription()- PHP
calendar->refreshSubscription- Go
Calendar.RefreshSubscription- Java
calendar().refreshSubscription- C#
Calendar.RefreshSubscriptionAsync- CLI
openemail calendar refresh-subscription
calendar.delete_subscription
Unsubscribe from a calendar
delete_subscription(id, api_key: nil) -> HashRemoves a subscription and every event it brought onto your calendar.
Parameters
idStringRequiredSubscription id,
csb_followed by 24 hex characters.api_keyStringOverrides the client's API key for this call only.
Returns
A Hash with object, id and deleted set to true.
Example
client.calendar.delete_subscription("csb_3f9a1c7e5b2d48a06c1e9f4b")Notes
A subscription that is not yours is a 404
calendar_subscription_not_found.
Also available in
calendar.import_ics
Import a calendar file
import_ics(data, filename: nil, api_key: nil) -> HashSends 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_import 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.
data is a binary String, an IO or a Pathname, and it goes out as text/calendar. Left out, filename: falls back to an upload's original_filename or the file's own name, so only plain bytes need it.
Parameters
dataString, IO or PathnameRequiredThe .ics file: a binary
String, anIOor aPathname.filenameStringThe name to show for the file in the list of imports, at most 255 characters. Left out, it is an upload's
original_filenameor the file's own name, and plain bytes are listed without a name.api_keyStringOverrides the client's API key for this call only.
Returns
A Hash for the import, shaped like the one get_import returns, with status set to queued.
Example
queued = client.calendar.import_ics(File.binread("work.ics"), filename: "work.ics") puts queued[:id], queued[:status]Notes
A body that is not an iCalendar file is a 400
not_a_calendar_file, an empty one a 400item_import_empty, and one holding more than 25,000 events a 400too_many_events.A file over 10 MB is a 413
item_import_too_large.Text you already hold, such as what
get_event_icsreturns, goes in as it is, since a String is sent byte for byte.An upload that outlasts the client
timeoutfails as a network error, so raise it on the client for a large file on a slow connection.Not retried automatically.
Also available in
calendar.list_imports
List calendar imports
list_imports(limit: nil, cursor: nil, api_key: nil) -> Nextmail::PageReturns one page of the calendar files and calendars brought in, newest first, each with what it added and what it left out. Beside the files sent with import_ics it lists the calendars that came with a mailbox import, and those carry the id of that import in parentImportId.
Paging is keyset. limit: takes 1 to 100 and defaults to 25, and next_cursor goes back as cursor: while has_more? is true. list_all_imports and iterate_imports do that walk for you.
Parameters
limitIntegerImports per page, a whole number from 1 to 100. The server defaults to 25.
cursorStringThe
next_cursorfrom the previous page. Never build one yourself.api_keyStringOverrides the client's API key for this call only.
Returns
An Nextmail::Page with items, has_more? and next_cursor. Each import is a Hash shaped like the one get_import returns.
Example
page = client.calendar.list_imports(limit: 50) page.items.each do |item| puts "#{item[:fileName]} #{item[:status]} #{item[:counts][:imported]} #{item[:counts][:skipped]}"endNotes
sourceisfilefor an upload.takeout,caldavandmicrosoftcame with a mailbox import.A cursor that names no import is a 400
invalid_cursor.A GET is retried automatically on network failure and on 408, 500, 502, 503 and 504 responses, up to the client's
max_retries, and on a 429 only when it carries aRetry-Afterof a minute or less.
Also available in
calendar.list_all_imports
Collect every calendar import into one array
list_all_imports(limit: nil, cursor: nil, api_key: nil) -> Array<Hash>Follows next_cursor from page to page and returns every calendar import, newest first.
Everything is held in memory before the call returns. Prefer iterate_imports when you can stop early. limit: sets the page size of each request, not the total.
Parameters
limitIntegerPage size per request, from 1 to 100, defaulting to 25 on the server.
cursorStringA cursor from an earlier page to start after.
api_keyStringOverrides the client's API key for every page of this walk.
Returns
An Array of Hashes holding every import across all pages.
Example
imports = client.calendar.list_all_imports added = imports.sum { |item| item[:counts][:imported] } puts "#{added} events came from #{imports.size} imports"Notes
A failure on any page raises out of the whole call, and the imports already fetched are discarded.
Also available in
calendar.iterate_imports
Stream calendar imports one at a time
iterate_imports(limit: nil, cursor: nil, api_key: nil, &block) -> Enumerator<Hash>Returns an Enumerator that yields calendar imports individually, newest first, or yields each one to a block when given one, and requests the next page only once the current one is drained. Nothing is fetched until you consume it, and breaking out of the loop stops the requests.
Parameters
limitIntegerPage size per request, from 1 to 100, defaulting to 25 on the server.
cursorStringA cursor from an earlier page to start after.
api_keyStringOverrides the client's API key for every page of this walk.
Returns
An Enumerator of Hashes, one import per step, or yields each one to a block.
Example
running = client.calendar.iterate_imports.find { |item| item[:status] == "running" } puts "still running #{running[:id]} #{running[:counts][:total]}" if runningNotes
The Enumerator is lazy, so an abandoned loop costs only the pages you consumed.
Also available in
calendar.get_import
Get a calendar import
get_import(id, api_key: nil) -> HashReturns 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. Poll it after import_ics until status is completed or failed.
counts[:imported] is what was added and counts[:skipped] what was left out, which report[:skipped] breaks down by reason: uid-taken for an event that was already here, no-start for one with no start time, invalid for one that could not be read and empty for a file or calendar that held no events.
Parameters
idStringRequiredCalendar import id,
iimp_followed by 24 hex characters.api_keyStringOverrides the client's API key for this call only.
Returns
A Hash with object, id, kind, source, one of Nextmail::ITEM_IMPORT_SOURCES, status, one of Nextmail::ITEM_IMPORT_STATUSES, fileName, fileBytes, parentImportId, counts, report, lastError, undoable and when it was created, started, finished and undone in createdAt, startedAt, finishedAt and undoneAt. counts holds total, imported, merged, skipped and failed. report holds collections, an Array of Hashes with name and items, skipped, a Hash of counts keyed by reason, and samples, an Array of Hashes with name and reason.
Example
item = client.calendar.get_import("iimp_3f9c2a7b1e4d8f60a5c7b92d") puts item[:status], item[:counts][:imported], item[:counts][:skipped], item[:report][:skipped][:"uid-taken"] || 0 item[:report][:samples].each { |sample| puts "#{sample[:name]} #{sample[:reason]}" }Notes
An id that names no calendar import is a 404
item_import_not_found.The reasons in
report[:skipped]are Symbol keys like every other key, so one with a hyphen is read asreport[:skipped][:"uid-taken"].A GET is retried automatically on network failure and on 408, 500, 502, 503 and 504 responses, up to the client's
max_retries, and on a 429 only when it carries aRetry-Afterof a minute or less.
Also available in
calendar.undo_import
Remove what a calendar import added
undo_import(id, api_key: nil) -> HashDeletes 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.
Parameters
idStringRequiredCalendar import id,
iimp_followed by 24 hex characters.api_keyStringOverrides the client's API key for this call only.
Returns
The import Hash, shaped like the one get_import returns, with status set to undone and undoneAt set.
Example
undone = client.calendar.undo_import("iimp_3f9c2a7b1e4d8f60a5c7b92d") puts undone[:status], undone[:undoneAt], undone[:counts][:imported]Notes
An import that is still running, or was already removed, is a 409
item_import_not_undoable.undoableon the import says whether the call would remove anything.An id that names no calendar import is a 404
item_import_not_found.Not retried automatically.