Nylas Calendar API overview
The Nylas Calendar API gives your application a secure, reliable connection to your end users' calendars. Sync historic and live events into your application in real-time.
The Nylas Calendar API provides a REST interface that includes the functionality to:
- Access data for calendars and events, such as event titles, location, description, dates, and more.
- Schedule events, send notifications, and RSVP to existing events.
What is a calendar?
Each account connected to Nylas can have either zero, one, or multiple calendars. Each calendar contains a collection of individual events. The calendar object is very simple and mostly serves as a container for events.
Types of calendars
Provider calendars
The primary calendar of the account usually uses the same name as the email address, or is sometimes just named "Calendar." Users may also have other custom calendars, access to colleagues' calendars, or access to shared team calendars. Check out our documentation on Events for more details.
Events can be viewed, added, modified, and deleted on calendars where read_only is false. Changes are automatically synced back to the provider.
Limited calendar support for IMAP providers
IMAP is a protocol for receiving email only. "IMAP" service providers use the IMAP protocol to receive mail, and the SMTP protocol to send it. Neither of these protocols includes calendar functionality.
However some IMAP providers, such as iCloud, support calendar functionality using other protocols such as CalDAV, which Nylas can use.
Use the Detect provider endpoint to check if Nylas can automatically connect to your provider. If not, then you need to enter the IMAP settings manually and you will only see an emailed events calendar (described below).
Emailed events calendars
All accounts also include a special calendar called "Emailed events" which contains event invitations that have been sent to the user's mailbox. This calendar is read-only which means events can't be added, updated, or deleted. However, the events can handle RSVPs. See the Events documentation for more details.
Virtual calendars
Virtual Calendars are used when you need to schedule people or objects that don't have an associated calendar. Review our documentation on the Virtual Calendar to learn more.
Calendar API endpoints
This section covers all of the endpoints the Nylas Calendar API provides to enable you to integrate full calendar functionality into your app.
Calendars
Each account connected to Nylas can have either zero, one, or multiple calendars, and each calendar contains a collection of individual events. Accounts can have many calendars, including a primary calendar, shared team calendars, read access to colleagues' calendars, and other custom calendars.
Calendars that are associated with email accounts typically have a primary calendar for the user's email, as well as an emailed events calendar that contains events that have been sent to a user's email inbox.
Events
Events are objects within a calendar that generally support all features and attributes of modern scheduling apps such as event names, list of participants, descriptions, location, time, and more.
Nylas supports all event functionality you expect, including sending email invites, RSVP status checks, notifications, creating events, modifying events, and recurring events.
Powered by calendar
The Nylas products that use Calendar are explained below.
Scheduler
The Nylas Scheduler is the fastest way to add full calendar functionality to your application, allowing your users to create highly customizable scheduling pages. Attendees and organizers can easily view availability and book meetings using your application without needing third-party scheduling solutions.
Virtual calendar
Virtual Calendars work like any other calendar and make it easy to embed customized scheduling features into your application. They're ideal for situations where you need to schedule events for people or objects that aren’t associated with an existing calendar account.
Virtual Calendars allow you to provide scheduling functionality to your users without requiring them to connect a third-party service provider such as Google, Exchange, or Office 365.
More resources
The Nylas Samples Github repos include working example apps in several languages that use the Nylas Calendar APIs.
Some interesting examples include: