Nylas Docs

The Nylas Developer Hub

Welcome to the Nylas developer hub. You'll find comprehensive guides and documentation to help you start working with Nylas as quickly as possible, as well as support if you get stuck. Let's jump right in!

Developer Guide

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 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, and our Python SDK makes it simple to create events in user accounts.

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

  1. Setup your Nylas developer account and get your API keys
  2. Install the Nylas Python SDK
  3. Read calendar events, create an event and send notifications to participants, and RSVP to events
  4. Explore the Nylas Calendar API

👍

Create Your Free Developer Account

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

Setup Your Developer Account

After signing up for your Nylas developer account, follow our guide to get your API keys and authorize your first email account. When you complete this guide, you should have three tokens that you need to run the code examples found below:

  • CLIENT_ID - The CLIENT ID found on the dashboard page for your Nylas App
  • `CLIENT_SECRET - The CLIENT SECRET found on the dashboard page for your Nylas App
  • ACCESS_TOKEN - The Access token provided when you authenticate an account to your Nylas App

Install the Nylas Python SDK

Prerequisites

  • Ensure you have pip installed on your development environment.
  • Create a virtual environment to install Nylas.

Refer to the official Python documentation on pip and virtualenv to learn more about how to set this up.

Installing the SDK

With your virtual environment activated, run pip install nylas.

Congrats! 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, and create a new instance of this class, passing the variables you gathered when you got your developer API keys. In the following example, replace CLIENT_ID, CLIENT_SECRET, and ACCESS_TOKEN with your values.

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

🚧

Take care with your secrets

It’s not best practice to include secrets like this in your code. A more secure way to provide these values is to store them as environment variables and access them with the os.environ module.

Read Calendar Events

Many user accounts have access to multiple calendars; you can access these via the nylas.calendars object. Available calendars include the default calendar, any calendars the user has created, and any calendars they have 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 via email invite; this calendar will be important later when we RSVP to an event.

In the following example, .all() is called to return all calendars associated with the account, and log each of the calendars’ name, id, and read_only values. The name and id values are useful for identifying and referring to specific calendars, and read_only 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("Name: {} | Description: {} | Read Only: {}".format(
    calendar.name, calendar.description, calendar.read_only))

Review the API reference for the calendar endpoints to learn more about what Nylas enables you to do with user calendars.

The nylas.events object makes it easy to access information about a user’s events. The next example will return the next 10 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. If also defines calendar as the first calendar that is returned for the acocunt.

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

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

Next, .all() is used to return the list of events and the limit argument limits the number of events that are returned to 5. Check out the API reference for 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 reference for the event endpoints to learn more about the attributes the event object contains.
Here 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
    ))
Ready to Build Your Calendar Integration?

Create an Event and Send Invitations

Now, it’s time to create a new event and start adding content to it:

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. Take a look at the API reference for events to learn more about the parameters you can assign to an events object.

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, while name 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, or datespan. Take a look at the reference documentation for event subobjects to learn more. Pro tip: datetime is a very effective python module for converting UTC timestamps to a human readable format.

Finally, we’ll save the event to the calendar and notify the participants. For this, you will need the ID for the calendar that the user has write access to. Take a look at the quickstart example for reading calendars and events to learn how to find a calendar ID. Then, in the following example, replace CALENDAR_ID with the appropriate value.

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

One important note is that notify_participants is set to false by default. If you want to send email notifications to participants, this must be set to true.

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')
Ready to Build Your Calendar Integration?

Respond to Event RSVP

Now it’s time to take a look at how to RSVP to events.

event = nylas.events.where(calendar_id="Emailed_Events_ID", title="Birthday Party!").first()
event.rsvp("yes", "I can't wait to see the birthday girl!")

This script uses .where() to return a filtered list of events, providing the following arguments

  • calendar_id - the id for the “Emailed Events” calendar that contains all event invites the user has received via email. This is the only calendar for which the RSVP function works. Replace EMAILED_CALENDAR_ID with the appropriate value.
  • title - the title of the event to RSVP to.

Head to the API reference to learn about how filters work.
If you know the id of the specific event that you want to RSVP to, you can also use nylas.events.get('{event_id}') to select a specific event, replacing {event_id} with the appropriate value.
Finally, event.rsvp() is called to send a 'yes' response, along with an RSVP message. You can also pass 'no' or 'maybe' to .rsvp(). Check out the API reference for the RSVP endpoint to learn more.
Here is the entire code example to RSVP to calendar events.

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

event = nylas.events.where(calendar_id="Emailed_Events_ID", title="Birthday Party!").first()
event.rsvp("yes", "I can't wait to see the birthday girl!")
Ready to Build Your Calendar Integration?

Explore the Nylas Calendar API

If you’ve made it this far, congrats, you’ve created your very first calendar event with the Nylas Calendar API! There is plenty more that you can do with it; take a look at the following resources to learn more about the Nylas Communications Platform capabilities.

Updated 3 months ago

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.

Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.