Version:
Only show these results:

Using Nylas Scheduler

💡 Looking for the Scheduler API references? You can find them here!

Nylas Scheduler v3 introduces a robust, flexible, and secure scheduling solution that you can integrate seamlessly into your project. With the Scheduler API and the Scheduler UI Components, you can manage bookings, design complex scheduling flows, customize the scheduling UI, and much more.

How Scheduler works

At its core, Scheduler is made up of two parts: the Scheduler Editor and Scheduling Pages. The Scheduler Editor lets organizers create and manage their Scheduling Pages. When an organizer creates a Scheduling Page, they set the event details (the title, duration, and which calendar to check availability against).

Guests use Scheduling Pages to book a time with the event organizer. When a booking is confirmed, Scheduler displays a booking confirmation message and sends a confirmation email to all participants.

Organizers can also customize their Scheduling Pages to include links to reschedule or cancel a booking, include extra fields in the booking form, add their company's logo to email notifications, and more.

Scheduler supports one-on-one, collective, and round-robin meetings.

User roles in Scheduler

Nylas Scheduler recognizes three types of users: organizers, participants, and guests.

📝 Participants and guests are sometimes collectively called "attendees". This includes optional guests that users can invite to the event.

  • Organizers: Users who can create Scheduling Pages and events. Only one organizer can exist per Configuration object.
  • Participants: Participants are attendees from the organizer's team or company. All participants are defined in the Configuration object.
  • Guests: Guests are external users who book an event with participants.
  • Additional guests: Other users who are invited by the guest who books the event. Their attendance is optional.

Set up Scheduler

To follow along with the samples on this page, you first need to sign up for a Nylas developer account, which gets you a free Nylas application and API key.

For a guided introduction, you can follow the Getting started guide to set up a Nylas account and Sandbox application. When you have those, you can connect an account from a calendar provider (such as Google, Microsoft, or iCloud) and use your API key with the sample API calls on this page to access that account's data.

Before you start with Scheduler, Nylas recommends you choose your implementation approach and hosting preference for Scheduling Pages, and decide whether to implement the Scheduler Editor.

Choose your implementation approach

You can use either UI Components or the Scheduler API to add Scheduler to your project.

  • You can add Scheduler UI Components to your project as web (HTML/Vanilla JS) or React components, then customize and extend them according to your needs. This is the simplest way to integrate Scheduler.
  • If you use the Scheduler APIs, you can create Configurations and manage bookings using API requests. You need to build your own UI, however.

Choose a hosting option for Scheduling Pages

Nylas offers two hosting options for your Scheduling Pages:

  • Nylas-hosted: When you create a public Configuration with a page URL ("slug"), Nylas automatically hosts the Scheduling Page under the book.nylas.com subdomain.
  • Self-hosted: You host and manage your Scheduling Pages within your own infrastructure.

(Optional) Implement Scheduler Editor

You can use Scheduler with or without the Scheduler Editor. The Scheduler Editor lets organizers create and manage Scheduling Pages, including their customization options.

⚠️ If you choose to use the Scheduler Editor for your Nylas-hosted Scheduling Pages, you're responsible for setting up the Scheduler Editor Component.

If you plan to use the Scheduler Editor, you need to decide on the authentication method you'll use for the Scheduler Editor Component.

  • Standard: Configures nylasSessionsConfig in your application. Guests are required to log in every time their access token expires. Nylas recommends using this method if you don't have an auth system set up.
  • Existing Hosted Authentication: Uses your application's existing Nylas Hosted Auth flow. Guests don't have to sign in multiple times.
  • Access token: Uses an access token for guests who have already authenticated using the same origin. Guests don't have to sign in multiple times.

Install UI Components

Scheduler offers the following pre-built, extensible web- (HTML/Vanilla JS) and React-based UI Components:

  • Scheduler Editor Component: Allows you to create and customize the Scheduler Editor.
  • Scheduling Component: Allows you to create and customize the Scheduling Page.

Each Component includes...

  • Custom event handlers that let you define specific logic or behavior for user actions.
  • Composable components that let you customize how each sub-component is arranged and rendered in the UI.
  • Custom UI stylings that support CSS shadow parts for a higher level of customization.

For more information, see the UI Components references.

To use the web-based Components, include the CDN package links in your project. You should use a specific version to ensure stability.

<!--Scheduling Component-->
https://cdn.jsdelivr.net/npm/@nylas/web-elements@1.1.4/dist/cdn/nylas-scheduling/nylas-scheduling.es.js

<!--Scheduler Editor Component-->
https://cdn.jsdelivr.net/npm/@nylas/web-elements@1.1.4/dist/cdn/nylas-scheduler-editor/nylas-scheduler-editor.es.js

If you want to use the React-based Components, install the npm package. You can use the @latest tag to pull the latest version to test, but you should use a specific version in Production to ensure stability.

npm install @nylas/react@1.3.5

Create a Configuration

You can create a Configuration using either the Scheduler API or the Scheduler Editor.

A Configuration is a collection of settings and preferences for an event. Nylas stores Configuration objects in the Scheduler database and loads them as Scheduling Pages. A Configuration can be either public or private, depending on whether it uses a [session].

  • A public Configuration doesn't require a session ID, so anyone with a link to the Scheduling Page can book an event. By default, Configurations are public.
  • A private Configuration requires a valid session ID to authenticate requests to the Availability and Bookings endpoints. When you use a private Configuration, you control who can create bookings from the Scheduling Page.

Create Configuration with Scheduler API

You can make a POST /v3/grants/<NYLAS_GRANT_ID>/scheduling/configurations request to create a Configuration. By default, Nylas creates a public Configuration that doesn't require a session.

curl --request POST \
  --url "https://api.us.nylas.com/v3/grants/<NYLAS_GRANT_ID>/scheduling/configurations" \
  --header 'Accept: application/json, application/gzip' \
  --header 'Authorization: Bearer <NYLAS_API_KEY>' \
  --header 'Content-Type: application/json' \
  --data '{
    "requires_session_auth": false,
    "participants": [{
      "name": "Nyla",
      "email": "nyla@example.com",
      "is_organizer": true,
      "availability": {
        "calendar_ids": ["primary"]
      },
      "booking": {
        "calendar_id": "primary"
      }
    }],
    "availability": {
      "duration_minutes": 30
    },
    "event_booking": {
      "title": "Testing Scheduler"
    }
  }'   
{
  "ID": "<SCHEDULER_CONFIGURATION_ID>",
  "participants": [{
    "name": "Nyla",
    "email": "nyla@example.com",
    "is_organizer": true,
    "availability": {
      "calendar_ids": ["primary"]
    },
    "booking": {
      "calendar_id": "primary"
    }
  }],
  "availability": {
    "duration_minutes": 30
  },
  "event_booking": {
    "title": "Testing Scheduler"
  }
}

Create Configuration with Scheduler Editor

⚠️ You need to have a working front-end UI to create Configurations with the Scheduler Editor. Follow the Scheduler Quickstart guide to get a local development environment up and running.

When you make a Scheduling Page using the Scheduler Editor, Nylas automatically creates a Configuration.

First, you need to include the Scheduler Editor script in your project and set nylasSessionsConfig. The Scheduler Editor Component uses the Hosted Authentication details you provide to interact with the Nylas APIs. For more information, see [Set up the Scheduler Editor Component].

<!-- scheduler-editor.html -->

<!DOCTYPE html>
<html class="h-full bg-white" lang="en">
  <head>
    <meta charset="UTF-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <title>Nylas Scheduler Editor Component</title>
    <link rel="preconnect" href="https://fonts.googleapis.com" />
    <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin />
    <link href="https://fonts.googleapis.com/css2?family=Inter:wght@100..900&display=swap" rel="stylesheet" />
    <script src="https://cdn.tailwindcss.com"></script>

    <style type="text/css">
      body {
        font-family: "Inter", sans-serif;
      }
    </style>
  </head>
  <body class="h-full">
    <div class="grid h-full place-items-center">
      <!-- Add the Nylas Scheduler Editor component -->
      <nylas-scheduler-editor />
    </div>

    <!-- Configure the Nylas Scheduler Editor component -->
    <script type="module">
      import { defineCustomElement } from "https://cdn.jsdelivr.net/npm/@nylas/web-elements@latest/dist/cdn/nylas-scheduler-editor/nylas-scheduler-editor.es.js";

      defineCustomElement(); 
      
      const schedulerEditor = document.querySelector("nylas-scheduler-editor");
      schedulerEditor.schedulerPreviewLink = `${window.location.origin}/?config_id={config.id}`;
      schedulerEditor.nylasSessionsConfig = {
        clientId: "<NYLAS_CLIENT_ID>", // Replace with your Nylas client ID from the previous section.
        redirectUri: `${window.location.origin}/scheduler-editor`,
        domain: "https://api.us.nylas.com/v3",
        hosted: true,
        accessType: "offline",
      };

      schedulerEditor.defaultSchedulerConfigState = {
        selectedConfiguration: {
          // Create a public Configuration that doesn't require a session.
          requires_session_auth: false,
          scheduler: {
            rescheduling_url: `${window.location.origin}/reschedule/:booking_ref`,
            cancellation_url: `${window.location.origin}/cancel/:booking_ref`
          }
        }
      };
    </script>
  </body>
</html>      
@import url('https://fonts.googleapis.com/css2?family=Inter:wght@100..900&display=swap');

html {
  height: 100%;
}

body {
  font-family: 'Inter', sans-serif;
  margin: 0;
  padding: 0;
  box-sizing: border-box;
  height: 100%;
}

Next, add the Scheduling Page script to your project.

<!-- index.html -->

<!DOCTYPE html>
<html class="h-full bg-white" lang="en">
  <head>
    <meta charset="UTF-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <title>Nylas Scheduling Component</title>
    <link rel="preconnect" href="https://fonts.googleapis.com" />
    <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin />
    <link href="https://fonts.googleapis.com/css2?family=Inter:wght@100..900&display=swap" rel="stylesheet" />
    <script src="https://cdn.tailwindcss.com"></script>

    <style type="text/css">
      body {
        font-family: "Inter", sans-serif;
      }
    </style>
  </head>
  <body>
    <div class="grid gap-0 h-full place-items-center">
      <div class="grid gap-4">
        <!-- A button to view the Scheduler Editor -->
        <a href="scheduler-editor.html" class="w-fit border border-blue-500 hover:bg-blue-100 text-blue-500 font-bold py-2 px-4 rounded">
          View Scheduler Editor
        </a>

        <!-- Add the Nylas Scheduling Component -->
        <nylas-scheduling></nylas-scheduling>
      </div>
    </div>

    <!-- Configure the Nylas Scheduling Component with a Configuration ID. -->
    <script type="module">
      import { defineCustomElement } from "https://cdn.jsdelivr.net/npm/@nylas/web-elements@latest/dist/cdn/nylas-scheduling/nylas-scheduling.es.js";

      defineCustomElement();

      const nylasScheduling = document.querySelector("nylas-scheduling");
      nylasScheduling.schedulerApiUrl = "https://api.us.nylas.com";

      // Get the Configuration ID from the URL (`?config_id=<NYLAS_SCHEDULER_CONFIGURATION_ID>`).
      const urlParams = new URLSearchParams(window.location.search);

      // If `config_id` doesn't exist, throw a `console.error`.
      if (!urlParams.has("config_id")) {
        console.error(
          "No Scheduler Configuration ID found in the URL. Please provide a Configuration ID."
        );
      }

      // Set the Configuration ID.
      nylasScheduling.configurationId = urlParams.get("config_id");
    </script>
  </body>
</html>   
#root {
  display: grid;
  place-items: center;
  height: 100%;
}
  
#root > div {
  display: grid;
  gap: 1rem;
}

.button {
  width: fit-content;
  padding-left: 1rem;
  padding-right: 1rem;
  padding-top: 0.5rem;
  padding-bottom: 0.5rem;
  font-weight: 700;
  color: rgb(59, 130, 246);
  text-decoration: inherit;
  border-width: 1px;
  border-radius: 0.25rem;
  border-color: rgb(59, 130, 246);
  border-style: solid;
}

(Optional) Create a session

🚀 If you created a public Configuration in the previous step, you skip this step and [set up the UI Components].

Next, make a Create Session request with the ID of your Configuration object. Nylas recommends you set a Time-to-Live (TTL) value for each session, and manually refresh sessions as they expire.

curl --request POST \
  --url "https://api.us.nylas.com/v3/scheduling/sessions" \
  --header 'Accept: application/json, application/gzip' \
  --header 'Authorization: Bearer <NYLAS_API_KEY>' \
  --header 'Content-Type: application/json' \
  --data '{
    "configuration_id": "<SCHEDULER_CONFIGURATION_ID>",
    "time_to_live": 10
  }'   
{
  "request_id": "1",
  "data": {
    "session_id": "<SCHEDULER_SESSION_ID>"
  }
}

Set up UI Components

🚀 If you created a Configuration with the Scheduler Editor, you can skip this step.

Scheduler offers two UI Components that you can integrate with your project: the Scheduler Editor, which lets you modify your Configuration in the UI, and the Scheduling Component, which loads the specified Scheduling Page.

Set up Scheduler Editor Component

Use the nylasSessionsConfig property to configure the Hosted Authentication information for the Scheduler Editor Component.

<html>
  <body>
    <nylas-scheduler-editor />
    <script type="module">
      import { defineCustomElement } from "https://cdn.jsdelivr.net/npm/@nylas/web-elements@latest/dist/cdn/nylas-scheduler-editor/nylas-scheduler-editor.es.js";

      defineCustomElement();

      const schedulerEditor = document.querySelector("nylas-scheduler-editor");

      schedulerEditor.nylasSessionsConfig = {
        clientId: '<NYLAS_CLIENT_ID>',
        redirectUri: `${window.location.origin}/scheduler-editor`,
        domain: 'https://api.us.nylas.com/v3',
        hosted: true,
        accessType: 'offline'
      }
    </script>
  </body>
</html>   
import React from 'react';
import { NylasSchedulerEditor } from "@nylas/react";

function App() {
  return (
    <NylasSchedulerEditor
      nylasSessionsConfig={{
        clientId: "<NYLAS_CLIENT_ID>",
        redirectUri: `${window.location.origin}/scheduler-editor`,
        domain: "https://api.us.nylas.com/v3",
        hosted: true,
        accessType: 'offline'
      }}
    />
  );
}

export default App;

The Scheduler Editor Component uses the Hosted Authentication details in nylasSessionsConfig to interact with the Nylas APIs.

💡 If you're already using Hosted Auth in your Nylas application, or you want to use Custom Auth, you can use the nylasApiRequest property to update your auth settings.

Set up Scheduling Component

The Scheduling Component requires either a sessionId (private Configuration) or configurationId (public Configuration) to load the Scheduling Page.

<html>
  <body>
    <nylas-scheduling configurationId="<SCHEDULER_CONFIG_ID>" /> 
      <!-- OR set the Scheduler session ID if using private Configuration (`requires_session_auth=true`) -->
      <!-- sessionId="<SCHEDULER_SESSION_ID>" --> 

    <script type="module">
      import { defineCustomElement } from "https://cdn.jsdelivr.net/npm/@nylas/web-elements@latest/dist/cdnnylas-scheduling/nylas-scheduling.es.js";
          
      defineCustomElement();
      
      ...
    </script>
  </body>
</html>   
import React from 'react';
import { NylasSchedulerEditor } from "@nylas/react";

function App() {
  return (
    <NylasScheduling
      // Set the Scheduler Configuration ID if using public Configuration (`requires_session_auth=false`)
      configurationId={"<SCHEDULER_CONFIG_ID>"}

      // OR set the Scheduler session ID if using private Configuration (`requires_session_auth=true`)
      // sessionId={"<SCHEDULER_SESSION_ID>"} 
    />
  );
}

export default App;

By default, the Scheduling Component renders all its sub-components (mode="app"). If you don't configure the app mode, Scheduler follows the standard booking flow. See Using the Scheduling Component for more information about Configuration modes.

Set up meeting reminders

Nylas can send email or webhook notification reminders for upcoming events. When you set up a reminder, you can configure the reminder type, time, recipients (email only), and email subject (email only).

You can set up reminders using either the Scheduler API or the [Scheduler Editor].

Set up reminders using Scheduler API

Make a Create Configuration or Update Configuration request that includes the reminders array.

📝 If you want to get reminders using webhook notifications, you also need to subscribe to the booking.reminder webhook trigger.

curl --request PUT \
  --url "https://api.us.nylas.com/v3/grants/<NYLAS_GRANT_ID>/scheduling/configurations/<SCHEDULER_CONFIGURATION_ID>" \
  --header 'Accept: application/json, application/gzip' \
  --header 'Authorization: Bearer <NYLAS_API_KEY>' \
  --header 'Content-Type: application/json' \
  --data '{
    "event_booking": {
      "reminders": [{
        "type": "email",
        "minutes_before_event": 30,
        "recipient": "all",
        "email_subject": "Meet Nylas in 30 minutes!"
      }]
    }
  }'   
curl --request PUT \
  --url "https://api.us.nylas.com/v3/grants/<NYLAS_GRANT_ID>/scheduling/configurations/<SCHEDULER_CONFIGURATION_ID>" \
  --header 'Accept: application/json, application/gzip' \
  --header 'Authorization: Bearer <NYLAS_API_KEY>' \
  --header 'Content-Type: application/json' \
  --data '{
    "event_booking": {
      "reminders": [{
        "type": "webhook",
        "minutes_before_event": 30
      }]
    }
  }'

Set up reminders using Scheduler Editor

You can use the nylas-reminder-emails component to let organizers create and manage email reminders from the Scheduler Editor UI.

By default, the Scheduler Editor includes the Communications tab, where organizers can customize their confirmation and reminder emails. To create a reminder, navigate to the Communications tab, click New reminder, and set the reminder details.

What's next?

Now that you have Scheduler set up, it's time to dive deeper. 🚀