Build for free
Manage Team Schedules With The Nylas Calendar API

Help Users Streamline Scheduling With The Nylas Calendar API

• 11 min read
Jump to section
    Author: Ben Lloyd Pearson
    Ben Lloyd Pearson
    Tags:
    Featured articles
    Nylas Ranks on the 2024 Deloitte Technology Fast 500™ for the Third Consecutive Year
    • 5 min read
    Read more
    ExtractAI
    Introducing Nylas ExtractAI: Sync, filter, and extract structured data from your user’s inbox
    • 8 min read
    Read more
    API v3 Calendar API Scheduler
    Introducing the new Nylas Scheduler: Experience the future of in-app scheduling
    • 4 min read
    Read more
    Jump to section

    When your app’s user is a manager overseeing a team that meets with external clients and prospects regularly, it’s her job to ensure the workload is spread evenly across the team. However, she doesn’t always have insight into how often and when her team is on calls and in meetings because this information is scattered across multiple calendars. The Nylas Calendar API makes it easy to centralize all of this data and to streamline the scheduling process within your app.

    With Nylas, you can streamline the scheduling process and give your users key insights into team bandwidth and customer lifecycle stage with a full-featured scheduling & analytics system within your app. This data gives managers key insights into workload capacity so they can identify who might have the bandwidth to take additional meetings. It’s also useful to keep tabs on the stage the prospects or clients are at within the customer lifecycle; new prospects need different support than prospects who are on the verge of making a buy.

    Let’s take a look at how the Nylas Communications Platform can power the infrastructure for your scheduling & analytics integration.

    Help Your Users Take Control of Their Scheduling

    The Nylas Communications Platform provides simple REST APIs for email, calendar, and contacts and makes it easy to integrate 100% of all email, calendar, and contacts providers into your app. Nylas enables you to quickly build your email, calendar, and contacts functionality so you can focus on the features your users love.

    This blog will show you how to add the following value to your app:

    You’ll learn how to use Nylas as the foundation for features your users will love. Ready to turn your app’s scheduling functionality up a notch? Let’s take a look at how to build functionality like this:

    Integrate complex scheduling functionality with Nylas

    How to Use Nylas To Build Your Email, Calendar, & Contacts Integration

    Now, we’ll take a look at what it takes to use the Nylas Email, Calendar, and Contacts APIs to add new functionality to your app. For this example, we’ll use the Nylas Python SDK, but we also offer SDKs for JavaScript (Node.js), Java, and Ruby.

    Before starting, you’ll need to take 30 seconds to register your Nylas account and get your developer API keys. Specifically, you need the Client ID and Client Secret for your Nylas app, and an access token for an email account that you want to use. We’ll save these as environment variables so they’re more secure; take a look at our guide on Python environment variables to learn more.

    You also need to install the nylas package by heading over to the terminal and running the command pip install nylas. Now we’re ready to start writing code!

    Initialize The Nylas Client

    To start, import the os and datetime packages; os lets us access our system’s environment variables and datetime will make it easier to access events within specific timeframes. We also need to import the APIClient object from nylas which allows us to make requests to the Nylas Communications Platform.

    from nylas import APIClient
import os
import datetime

CLIENT_ID = os.environ['CLIENT_ID']
CLIENT_SECRET = os.environ['CLIENT_SECRET']
ACCESS_TOKEN = os.environ['ACCESS_TOKEN']

# Initialize a Nylas client object that uses your user's access token
nylas = APIClient(
    CLIENT_ID,
    CLIENT_SECRET,
    ACCESS_TOKEN
)

    Find Important Upcoming Meetings on a Team’s Calendar

    Now, it’s time to identify all of the important meetings we have with prospects coming up this week. For this example, we’ll assume our sales team is putting all of their meetings onto a shared calendar named “Prospect Meetings.” To do so, We’ll use the /calendar and /events endpoints to find all events that exist on this calendar for the current working week.

    Start by searching all of the user’s calendars for one named “Prospect Meetings” and save the calendar ID for later.

    # Retun all calendars for a user account
calendars = nylas.calendars.all()
# Get the ID of the "Prospect Meetings" calendar
calendar_id = [ calendar['id'] for calendar in calendars if 'Prospect Meetings' in calendar['name'] ][0]

    In addition to the calendar name and ID, the /calendars endpoint also provides things like the calendar description, and a read_only boolean that indicates if the user has read or write access to the calendar. This is an example of the JSON payload Nylas returns: 

    {
  "description": "A shared team calendar to keep track of meetings with external prospects",
  "id": "67qmz3fuk9wf***",
  "name": "Calendar",
  "account_id": "bh1vu31mw9ap***",
  "object": "calendar",
  "read_only": false
}

    Now let’s get a time representation of the current working week (Monday – Friday) that we’ll use to return events on the shared calendar. The Nylas Communications Platform standardizes all time representations from user calendars as an epoch timestamp, which makes it easy to compare times across multiple calendars. 

    today = datetime.date.today()

# Get Monday's datetime and convert it to a unix timestamp
monday = today + datetime.timedelta(days=-today.weekday(), weeks=1)
monday_unix = monday.strftime("%s")

# Get Friday's datetime and convert it to a unix timestamp
friday = monday + datetime.timedelta(days=5)
friday_unix = friday.strftime("%s")

    The Nylas Calendar API returns events as JSON payloads that contain all of the information you’d expect to find in an event, including the title, description, start and end time, participants, and more. They are first class objects, meaning that you can interact with them without any prior knowledge of the calendars they exist on. Now, let’s use the calendar ID and two timestamps we got above to find all events on the Prospect Meetings calendar for this week.

    # Find all events on the Prospect Meetings calendar between this Monday and Friday
events = nylas.events.where(
  calendar_id=calendar_id, 
  starts_after=monday_unix, 
  ends_before=friday_unix
)

    This stores a list of events to the events variable, and we can now return these events individually for our weekly calendar. Here is an example of what these events look like, take particular note of the participants attribute, this will be important later.

    {
    "title": "New Kite Technology",
    "description": "Let's discuss the newest kite technology.",
    "participants": [
        {
            "comment": "This would be great for my experiments!",
            "email": "[email protected]",
            "name": "Benjamin Franklin",
            "status": "yes"
        },
        {
            "comment": null,
            "email": "susan@my_company.com",
            "name": "Susan Seller",
            "status": "yes"
        }
    ],
    "read_only": false,
    "status": "confirmed",
    "when": {
        "start_time": 1478565000,
        "end_time": 1478568600,
        "object": "timespan"
    },
    "calendar_id": "412pwfsq3k7uklj1zkq5",
    "id": "c7n5vl6dhbdeqwjaxk29",
    ...
}

    Note: this example has been abbreviated, head over to the API reference to learn about the other attributes events objects contain.

    Make it Easy to Keep Track of Meeting Participants

    We‘re going to create a dashboard that tracks information for both our internal sales team and the external prospects they’re meeting with. This means we’ll need to sort the list of participants according to whether they are an employee of our company, or an external prospect. These lists will be used later. The following code checks the participants attribute of the event and creates a list for each of these. We will also save the time of this meeting to a variable that we’ll need later.

    internal_employees = []
external_prospects = []
this_meeting = {}
for event in events:
    for participant in event["participants"]:
        # If our company domain is in the participant's email, they're our employee
        if '@my_company.com' in participant["email"]:
            if participant["email"] not in internal_employees:
                internal_employees.append(participant["email"])
        # Anyone who isn't in our company should be appended to external_prospects
        else:
            if participant["email"] not in external_prospects:
                external_prospects.append(participant["email"])
                this_meeting[participant["email"]] =  event["when"]["start_time"]

    Help Users Gain Insights Into Team Capacity

    One component of our app will show how close to capacity our sales team is this week. For this example, we’ll make the assumption that the sales people should spend a maximum of 25 hours a week in meetings. So, we’ll tabulate the amount of time they are spending in meetings with prospects this week using the when attribute for the events and display that number as a percent total with 25 being 100%.

    for employee in internal_employees:
    total_hours = 0
    for event in events:
        if employee in [participant["email"] for participant in event["participants"]]:
            # Nylas represents time as seconds since epoch time, we need to convert this to hours
            total_seconds = event["when"]["end_time"] - event["when"]["start_time"]
            total_hours += total_seconds / 60 / 60
    print("{} is spending {}% of their time in meetings this week".format(
        employee,
        ( total_hours / 25 ) * 100 ))

    Enrich Understanding With Contacts Data

    The Nylas Contacts API makes it easy to improve your calendar integration by providing access to detailed information found in the user’s contact book. We want our dashboard to show important information about the prospects like their job title, company name, and phone number. So, we’ll use their email address to look this information up in the user’s contact book.

    for prospect in external_prospects:
    contacts = nylas.contacts.where(email=prospect).all()
    if contacts:
        contact = contacts[0]
        # A contact can have multiple email addresses and phone numbers
        phone_number = next(iter(list(contact['phone_numbers'].values())), None)
        email = next(iter(list(contact['emails'].values())), None)

        print("Full Name: {} | Email: {} | Company Name: {} | Job Title: {} | Phone Number: {}".format(
            contact['given_name'] + " " + contact['surname'],
            email,
            contact['company_name'],
            contact['job_title'],
            phone_number,
            ))

    Here is an abbreviated example of the JSON payload for a one of the team’s prospects. Take a look at the API reference to learn more about the other attributes that are available.

    {
    "given_name": "Marie",
    "surname": "Curie",
    "job_title": "Physicist",
    "notes": "Status: Prospect",
    "office_location": "Warsaw, Poland",
    "company_name": "Radioactivity Inc.",
    "emails": [
        {
            "email": "[email protected]",
            "type": "work"
        }
    ],
    "phone_numbers": [
        {
            "number": "1 040 719 3466",
            "type": "mobile"
        }
    ],
    "picture_url": "https://api.nylas.com/contacts/abcd1234***/picture",
    "web_pages": [{
        "type": "homepage",
        "url": "https://radioactivity.com"
      }],
    ...
}

    Track Prospect Status

    The last thing we want to do is track the first meeting we’ve had with prospects so we have a better idea of where they are in the sales pipeline. Specifically, we want to identify which meetings this week are with new prospects. We can use the notes field of the Nylas Contacts API to store the contact’s current status in the sales pipeline and the date we first met with them.

    The next example will check to see if a status statement for the contact has already been added. 

    • If it has, we’ll search the Prospect Meetings calendar and return all events where the prospect is listed as a participant
    • If it hasn’t, we’ll add the line “Status: Prospect” and the date of the upcoming meeting, indicating that it’s the first time our team has met with the prospect.
    for prospect in external_prospects:
    # Search the user's contact book for any that have the email address of the event participant
    contacts = nylas.contacts.where(email=prospect).all()
    if contacts:
        contact = contacts[0]
        # Check to see if the contact already has a status statement in the notes field.
        if contact["notes"] and 'Status: ' in contact["notes"]:
            calendar_id = [ calendar['id'] for calendar in calendars if 'Prospect Meetings' in calendar['name'] ][0]
            all_events = nylas.events.where(calendar_id=calendar_id).all()
            for event in all_events:
                # Look for events on the calendar that include the prospect as a participant
                if prospect in [participant["email"] for participant in event["participants"]]:
                    # Return the dates we previously met with the prospect in a human-readable format
                    print("Met with {} on {}".format(
                        prospect,
                        datetime.datetime.fromtimestamp(event["when"]["start_time"]).strftime("%B %d, %Y - %H:%M:%S")
                        ))
        else:
            # If we've never met with this prospect before, record our upcoming meeting as the first meeting we've had with them.
            contact.notes = "Status: Prospect\nFirst Meeting: {}".format(
                    datetime.datetime.fromtimestamp(this_meeting[prospect]).strftime("%B %d, %Y - %H:%M:%S")
                    )
            contact.save()

    Want all of this code in one place? Head over to the docs.

    Nylas Takes Your Calendar & Contacts Integration Further

    The Nylas Communications Platform is the easiest way to integrate with 100% of calendar providers. Learn more about the ways Nylas can unify your users’ communications in your app in no time:

    Related resources

    Calendar Availability
    How to block time slots in Outlook and Google calendar with Nylas Calendar API

    Key Takeaways Managing calendar availability is essential for professionals, teams, and businesses to stay organized…

    • 14 min read
    Read more
    Webhooks
    How to Solve Webhook Integration Challenges with PubSub Notification Channel

    Key Takeaways This article addresses the challenges of webhook integration and introduces the PubSub Notification…

    • 6 min read
    Read more
    Email API
    How to Send Emails Using an API

    Key Takeaways This post will provide a complete walkthrough for integrating an email API focused…

    • 18 min read
    Read more