Events with Python

The Nylas Python SDK is the quickest way to integrate calendars into your app with Python and the Nylas Calendar API. Build your calendar integration in 15 minutes.

Python Calendar Create

Create Your Free Developer Account

Ready to build your email integration? Create your Nylas developer account to get started.

Python is one of the most popular programming languages in the world due to its extensive collection of libraries, easy to understand syntax, and practical abstraction capabilities. In fact, we love Python so much that we’ve used it to build the Nylas Communications Platform which enables developers to quickly integrate email, calendar, and contacts into their app. The Nylas Calendar API connects to all major providers including Google, Exchange, iCal, Outlook, and more

This guide explains how to use the Nylas Python SDK and Calendar API to create events. It covers the following steps:

Setting up your Nylas developer account and getting your API keys.
Installing the Nylas Python SDK.
Reading calendar events, creating events and sending notifications to participants, and RSVPing to events.
Exploring the Nylas Calendar API.

Prerequisites

Before you can start using the Nylas Python SDK, you'll need to do the following:

Sign up for your Nylas developer account.
Get your Nylas keys:
- CLIENT_ID: The client ID for your application in the Nylas Dashboard.
- CLIENT_SECRET: The client secret for your application in the Nylas Dashboard.
- ACCESS_TOKEN: The access token provided when you authenticate an account to your Nylas application.
Make sure you have pip installed on your development environment.
Create a virtual environment to install Nylas.

Install the Nylas Python SDK

With your virtual environment activated, run pip install nylas.

Congratulations!

You’re now ready to write code with the Nylas Python SDK.

Configure the API Client

At its core, the Nylas Communication Platform is an API client that interfaces with all of the major email providers. First, import the APIClient class from the nylas package. Create a new instance of this class and pass in the variables you gathered when you received your developer API keys. In the example shown below, replace CLIENT_ID, CLIENT_SECRET, and ACCESS_TOKEN with your values.

from nylas import APIClient
nylas = APIClient(
  CLIENT_ID,
  CLIENT_SECRET,
  ACCESS_TOKEN
)

Be Careful with Secrets

Make sure to follow best practices when including authentication secrets like this in your code. Increase security by storing these values as environment variables.

Read Calendar Events

Many user accounts have access to multiple calendars which you can access using the nylas.calendars object. Available calendars include the default calendar, any calendars the user has created, and any calendars they've added, such as those for other users or for their teams.

The "Emailed Events" calendar is a unique calendar that includes all events the user receives through an email invite. This calendar will be important later when we RSVP to an event.

In the example shown below, .all() is called to return all calendars associated with the account, and logs each of the calendars’ name, id, and read_only values. The name and id values are useful for identifying and referring to specific calendars. The read_only value is a boolean that lets you know whether the user has write access to the calendar.

calendars = nylas.calendars.all()
for calendar in calendars:
  print("Id: {} | Name: {} | Description: {} | Read Only: {}".format(
    calendar.id, calendar.name, calendar.description, calendar.read_only))

Review the API documentation for the calendar endpoints to learn more about what you can do with user calendars and Nylas.

The nylas.events object makes it easy to access information about a user’s events. The example below will return the next five events after the current moment in time on a user’s calendar:

now = int(datetime.now().timestamp())
calendar = nylas.calendars.first()
events = nylas.events.where(calendar_id=calendar.id, starts_after=now).all(limit=5)
for event in events:
  print("Title: {} | When: {} | Participants: {}".format(
    event.title, event.when, event.participants

First, the script defines the variable now, which is a Unix Epoch timestamp represented in seconds. This is the time format Nylas uses for event objects. It also defines calendar as the first calendar that is returned for the account.

Then, .where() is called with a few filters:

starts_after - This selects events that occur after the specified time. This example passes the Unix epoch timestamp we stored as the constant now.
calendar_id - This is the id for one of the user’s calendars. In this example, the script passes the id for the first calendar that's found for the user account.

Next, .all() is used to return the list of events and the limit argument limits the number of events that are returned to five. Check out our API documentation on pagination to learn more about using limits and offsets to paginate results.

Finally, the script iterates through the list of events and logs the title, time, and list of participants for each of them. Take a look at the API documentation for the event endpoints to learn more about the attributes the event object contains.

Below is the full code example for reading calendars and events from a user account:

from nylas import APIClient
nylas = APIClient(
  CLIENT_ID,
  CLIENT_SECRET,
  ACCESS_TOKEN
)

# Most user accounts have multiple calendars where events are stored
calendars = nylas.calendars.all()
for calendar in calendars:
  # Print the name and description of each calendar and whether or not the calendar is read only
  print("Name: {} | Description: {} | Read Only: {}".format(
    calendar.name, calendar.description, calendar.read_only))


  now = int(datetime.now().timestamp())
  # Get a calendar whose events we want to inspect.
  calendar = nylas.calendars.first()
  # Return the next 5 events on the user's calendar
  events = nylas.events.where(calendar_id=calendar.id, starts_after=now).all(limit=5)
  for event in events:
    print("Title: {} | When: {} | Participants: {}".format(
      event.title, event.when, event.participants
    ))

Create an Event and Send Invitations

Now, it’s time to create a new event and start adding content to it. An example is shown below:

event = nylas.events.create()
event.title = "New Years Party!"
event.location = "My House!"
event.description = "We'll ring in the new year in style!"

This example creates a new event object and assigns it a title and location. For more about events object parameters, view our API documentation on events.

Next, let’s set a time for this event and add a participant:

event.participants = [{"name": "My Friend", 'email': '[email protected]'}]
event.when = {"start_time": 1577829600, "end_time": 1577840400}

Participants are added as an array of participant subobjects and require an email field. The name field is optional.

Event times are set with UTC timestamps and can be one of four sub-objects that correspond to the time and duration of an event:

time
timespan
date
datespan

Datetime in Python

datetime is a very effective python module for converting UTC timestamps to a human readable format.

For CALENDAR_ID, you'll need the ID for the calendar that the user has write access to. Take a look at our quickstart example for reading calendars and events to learn how to find a calendar ID. Then, replace CALENDAR_ID with the appropriate value.

Finally, we’ll save the event to the calendar and notify the participants with the code below:

event.calendar_id = CALENDAR_ID
event.save(notify_participants='true')

The notify_participants value is set to false by default. If you want to send email notifications to participants, set this to true.

The entire example is shown below:

from nylas import APIClient

nylas = APIClient(
    CLIENT_ID,
    CLIENT_SECRET,
    ACCESS_TOKEN,
)

event = nylas.events.create()
event.title = "New Years Party!"
event.location = "My House!"
# Event times are set via UTC timestamps
# This example starts on December 31, 2019 at 10 PM GMT.
event.when = {"start_time": 1577829600, "end_time": 1577840400}

# Participants can be added via a list of participant subobjects
event.participants = [{"name": "My Friend", 'email': '[email protected]'}]

# CALENDAR_ID must be the value of a calendar the user account has write access to.
event.calendar_id = CALENDAR_ID
# Event emails are not sent by default
# Enable notify_participants to send an email notification to participants
event.save(notify_participants='true')

Explore the Nylas Calendar API

If you’ve made it this far, congrats! You’ve integrated your first calendar with the Nylas Calendar API. There's plenty more that you can do with it. Take a look at the following resources to learn more about the Nylas Communications Platform capabilities:

Learn about some of the more important features of the Nylas Calendar API.
Take a look at additional code examples for the Python SDK to see what else you can do with email, calendars, and contacts.
Follow our tutorials to learn about other aspects of the Nylas Email, Calendar, and Contacts APIs.
Read about how the Nylas Communications Platform works.
Browse the API documentation to learn about the features of the Nylas Communications Platform.
Read our blog post How to Manage Calendar Events with the Nylas Python SDK.