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 references.
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_dotenvload_dotenv()
import osimport sysfrom 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 references.
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 anemail
value. You can also include aname
. -
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. -
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
references.
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_dotenvload_dotenv()
import osimport sysfrom 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", } ], "notify_participants": "true" }, query_params={ "calendar_id": '<CALENDAR_ID>' })