Quickstart: Calendar and Events APIs

The Nylas Calendar and Events APIs offer everything you need to manage your users’ calendars and schedule events. This guide will walk you through setting up your Nylas application and making your first requests to the Calendar and Events APIs.

Before you begin

Before you start, you need to have a Nylas account. If you don’t have one already, you can create one here.

Create a Nylas application

1. Log in to the Nylas Dashboard.
2. On the All apps page, click Create new app.
3. Select the Data residency.
   This determines where Nylas stores your application and user data. Be sure to select the region where your project will be active. You can’t change this setting later.

4. Select the Environment.
5. Click Create application.

Generate an API key

You’ll need an API key for the last step.

1. On your application’s page, click API Keys in the left navigation.
2. Click Generate new key.
3. Enter an API key name and select the Expiration time.
4. Click Generate key.

Create a grant

1. On your application’s page, click Grants in the left navigation.
2. Click Add Account.

You’ll be prompted to enter your email address. If the authentication is successful you’ll see your email address and grant ID with a valid status on the Grants page.

Make your first API call

Now that you’re all set up, it’s time to make your first API call. 🚀 For this example, we’ll be using the Create a Calendar endpoint to create a calendar that will be a container for Event objects. Be sure to replace the placeholder fields with your grant ID and API key from the previous step.

RequestResponse (JSON)Node.js SDKPython SDKRuby SDKJava SDKKotlin SDK

curl --request POST \
  --url 'https://api.us.nylas.com/v3/grants/<NYLAS_GRANT_ID>/calendars' \
  --header 'Accept: application/json, application/gzip' \
  --header 'Authorization: Bearer <NYLAS_API_KEY>' \
  --header 'Content-Type: application/json' \
  --data '{
    "name": "My New Calendar",
    "description": "Description of my new calendar",
    "location": "Location description",
    "timezone": "America/Los_Angeles"
  }'

{
  "request_id": "1",
  "data": {
      "grant_id": "1",
      "description": "<string>",
      "id": "2",
      "is_primary": false,
      "location": "<string>",
      "metadata": {
          "your-key": "<string>"
      },
      "name": "<string>",
      "object": "calendar",
      "read_only": false,
      "timezone": "UTC",
      "is_owned_by_user": false
  }
}

import 'dotenv/config'
import Nylas from 'nylas'

const NylasConfig = {
  apiKey: process.env.NYLAS_API_KEY,
  apiUri: process.env.NYLAS_API_URI,
}

const nylas = new Nylas(NylasConfig)

async function createCalendar() {
  try {
    const calendar = await nylas.calendars.create({
      identifier: process.env.NYLAS_GRANT_ID,
      requestBody: {
        name: 'Nylas DevRel',
        description: 'Nylas Developer Relations',
      }
    })

    console.log('Calendar:', calendar)
  } catch (error) {
    console.error('Error to create calendar:', error)
  }
}

createCalendar()

from dotenv import load_dotenv
load_dotenv()

import os
import sys
from nylas import Client

nylas = Client(
    os.environ.get('NYLAS_API_KEY'),
    os.environ.get('NYLAS_API_URI')
)

grant_id = os.environ.get("NYLAS_GRANT_ID")

calendar = nylas.calendars.create(
    grant_id,
    request_body={
      "name": 'Nylas DevRel',
      "description": 'Nylas Developer Relations'
    }
)

print(calendar)

require 'nylas'

nylas = Nylas::Client.new(api_key: "<NYLAS_API_KEY>")

query_params = {
  calendar_id: "<CALENDAR_ID>"
}

request_body = {
  "name": "My New Calendar",
  "description": "Description of my new calendar",
  "location": "Location description",
  "timezone": "America/Toronto",
  "metadata": { "key1":"This is my metadata" }
}

calendar, _request_ids = nylas.calendars.create(
    identifier: "<NYLAS_GRANT_ID>",
    request_body: request_body)

puts calendar

import com.nylas.NylasClient;
import com.nylas.models.*;
import java.util.Map;

public class CreateCalendar {
  public static void main(String[] args) throws NylasSdkTimeoutError, NylasApiError {
    NylasClient nylas = new NylasClient.Builder("<NYLAS_API_KEY>").build();

    CreateCalendarRequest requestBody = new CreateCalendarRequest(
        "My New Calendar",
        "Description of my new calendar",
        "Location description",
        "America/Toronto",
        Map.of("key1", "This is my metadata"));

    Response<Calendar> calendar = nylas.calendars().
        create("<NYLAS_GRANT_ID>", requestBody);

    System.out.println(calendar.getData());
  }
}

import com.nylas.NylasClient
import com.nylas.models.*

fun main(args: Array<String>) {
  val nylas: NylasClient = NylasClient(apiKey = "<NYLAS_API_KEY>")

  val requestBody = CreateCalendarRequest(
      "My New Calendar",
      "Description of my new calendar",
      "Location description",
      "America/Toronto",
      mapOf("key1" to "This is my metadata")
  )

  val calendar: Response<Calendar> = nylas.calendars().
      create("<NYLAS_GRANT_ID>", requestBody)

  print(calendar.data)
}