Manage events with Python

This page explains how to use the Nylas Python SDK and Calendar API to create and manage events.

Before you begin

Before you start, you must have done the following tasks:

Installed and set up the Nylas Python SDK.
Authenticated one or more end users.

List calendars and events

To access the calendars associated with an end user's account, use the nylas.calendars object. You can access their default calendar and any custom calendars (for example, those that the end user created).

The following code sample shows how to retrieve five calendars from an end user's account.

calendars = nylas.calendars.list('<NYLAS_GRANT_ID>')
for calendar in calendars[0]:
  print("Id: {} | Name: {} | Description: {} | Read Only: {}".format(
    calendar.id, calendar.name, calendar.description, calendar.read_only))

For more information about calendars and their parameters, see the Calendar reference documentation.

To access the events associated with an end user's account, use the nylas.events object.

The following example shows how to query the Nylas APIs to retrieve the next five events from an end user's calendar, starting at the time that you make the request.

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')
)

calendars = nylas.calendars.list('<NYLAS_GRANT_ID>')
for calendar in calendars[0]:
  print("Id: {} | Name: {} | Description: {} | Read Only: {}".format(
    calendar.id, calendar.name, calendar.description, calendar.read_only))

events = nylas.events.list(
    '<NYLAS_GRANT_ID>',
    query_params={
      "calendar_id": '<CALENDAR_ID>'
    }
)

print(events)

You can fine-tune the results by setting certain parameters, like starts, to specify a time range, a maximum number of results, and any pagination settings.

For more information, see the Events reference documentation.

Create an event and send email notifications

The following code sample creates an event and assigns its title.

event = nylas.events.create(
    '<NYLAS_GRANT_ID>',
    request_body={
      "title": 'Build With Nylas',
    },
    query_params={
      "calendar_id": '<CALENDAR_ID>'
    }
)

Keep the following things in mind when you create events:

You add participants in the participants array. Each requires an email value. You can also include a name.

The when object specifies the event time in Unix timestamp format, represented in UTC. The event time can be one of the following categories:

Category	Properties	Description
Time	`time`, `timezone`	A specific point in time (for example, the start time of an event).
Timespan	`start_time`, `end_time`, `start_timezone`, `end_timezone`	A period of time with a specified beginning and end (for example, an hour-long lunch meeting).
Date	`date`	The date on which the event occurs, without a clock-based start or end time (for example, a birthday or holiday).
Datespan	`start_date`, `end_date`	A span of days without specific clock-based start and end times (for example, a business quarter or semester). For more information, see All-day event handling.

🔍 Datetime is a very effective Python module for converting UTC timestamps to a human-readable format. For more information, see the official Python documentation.

The calendar_id must be the ID for a calendar that the end user has Write access to. For information on retrieving calendar IDs, see List calendars and events.

When you create an event, you can set variables that change its attributes, such as its title and location. For more information on available attributes, see the POST /v3/grants/{grant_id}/events reference documentation.

After you create the event, use events.update() to save it to the end user's calendar.

event = nylas.events.update(
    '<NYLAS_GRANT_ID>',
    '<EVENT_ID>',
    request_body={
      "notify_participants": "true"
    },
    query_params={
      "calendar_id": '<CALENDAR_ID>'
    }
)

By default, Nylas sets notify_participants to false. This means that when you create an event, Nylas defaults to not sending email notifications. If you want to send notifications to participants, set notify_participants to true.

All together, the code to create an event and send email notifications resembles the following example.

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')
)

event = nylas.events.create(
    '<NYLAS_GRANT_ID>',
    request_body={
      "title": 'Build With Nylas',
      "when": {
        "start_time": 1609372800,
        "end_time": 1609376400
      },
    },
    query_params={
      "calendar_id": '<CALENDAR_ID>'
    }
)

updatedEvent = nylas.events.update(
    '<NYLAS_GRANT_ID>',
    '<EVENT_ID>',
    request_body={
      "participants": [
        {
          "name": "Nylas DevRel",
          "email": "devrel-@-nylas.com"
        }
      ],
      "notify_participants": "true"
    },
    query_params={
      "calendar_id": '<CALENDAR_ID>'
    }
)

Explore the Calendar API

If you've made it to this point, congratulations! You've learned how to manage events with the Nylas Python SDK and Calendar API! 🎉

There's plenty more that you can do with Nylas. Take a look at the following resources to learn more: