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

Google and Microsoft Contacts with Python

Learn how to manage Google & Microsoft contacts with the Nylas Python SDK. Build your contacts book 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. 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 Contacts API makes it very easy to create and modify contacts for your user’s Google and Microsoft accounts.

This guide explains how to use the Nylas Python SDK and Contacts API to create Google and Microsoft (Exchange, Outlook, Office365) contacts and modify their attributes. It covers the following steps:

  1. Set up your Nylas developer account and get your API keys
  2. Install the Nylas Python SDK
  3. Manage Google & Microsoft contacts
  4. Explore the Nylas Contacts API

👍

Create Your Free Developer Account

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

Set up Your Developer Account

After signing up for your Nylas developer account, follow our guide to get your API keys and authorize your first 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.

How to Manage Google & Microsoft Contacts

At its core, the Nylas Communication Platform is an API client that interfaces with all of the major contact book 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.

List Contacts

The next example demonstrates how to display the first and last name, email address, and ID for the first 10 contacts returned from an account. The first step is to get a list of contact objects. The following example uses the nylas object to return the first 10 contacts from the user account.

contacts = nylas.contacts.all(limit=10)

Next, we’ll iterate through the list of contact objects and return their first and last name, the first email address stored for the contact, and the contact id, which can be used to make modifications to the contact.

for contact in contacts:
    email = list(contact.emails.values())[0][0]
    print("Name: {} {} | Email: {} | ID: {}".format(
        contact.given_name, contact.surname, email, contact.id)
          )

This example defines email using contact.emails, which returns a defaultDict() object. This object contains a list of all email addresses associated with the account, along with their types, which can be personal, work, or Null. The example also uses contact.given_name and contact.surname to construct the contact’s full name. Take a look at the API reference for the contacts endpoint to learn more about the attributes the contact object contains.

Here is the entire code example to list contacts for a user account.

from nylas import APIClient

nylas = APIClient(
    CLIENT_ID,
    CLIENT_SECRET,
    ACCESS_TOKEN,
)

contacts = nylas.contacts.all(limit=10)
for contact in contacts:
    # contact.emails returns a defaultdict() object
    # that contains a list of email addresses with their appropriate labels
    email = list(contact.emails.values())[0][0]

    print("Name: {} {} | Email: {} | ID: {}".format(
        contact.given_name, contact.surname, email, contact.id)
          )
Ready to Build Your Contacts Integration?

Create a Contact

To create a contact, use nylas to create a new contact object:

contact = nylas.contacts.create()

Now it’s time to define some attributes for this new contact:

contact.given_name = "My"
contact.middle_name = "Nylas"
contact.surname = "Friend"
contact.emails['work'] = ['[email protected]']
contact.notes = "Make sure to keep in touch!"
contact.phone_numbers['business'] = ['(555) 555-5555']
contact.web_pages['homepage'] = ["https://nylas.com"]

There is quite a bit happening here, so let’s break it all down.

  • contact.given_name, contact.middle_name, and contact.surname define the first, middle, and last name for the contact.
  • contact.emails adds an email address to the contact and sets the type to work. You can also specify personal as a type.
  • Similarly, contact.phone_numbers attaches a phone number to the contact using the type business; Google and Microsoft label this as the contact’s work phone number. This label must be one of business, organization_main, mobile, assistant, business_fax, home_fax, radio, car, home, or pager.
  • Finally, contact.web_pages connects a website URL to the contact with the label homepage. This label must be one of homepage, profile, work, or blog.

Take a look a the API reference for the contact creation endpoint to learn more about the attributes you can assign to a contact object.

The very last thing you need to do is call .save() on the contact object. This saves the contact to Nylas, which then syncs the new contact to the third party provider.

contact.save()

Once the contact has been saved and synced to Google, you should see a contact that looks something like this:

Here is an example of the same contact in Microsoft Outlook.

For convenience, here is the entire code example for creating a contact.

from nylas import APIClient

nylas = APIClient(
    CLIENT_ID,
    CLIENT_SECRET,
    ACCESS_TOKEN,
)

contact = nylas.contacts.create()
# Add a first, middle, and last name for the contact.
contact.given_name = "My"
contact.middle_name = "Nylas"
contact.surname = "Friend"

# Email address 'type' must be either 'work' or 'personal'
contact.emails['work'] = ['[email protected]']
contact.notes = "Make sure to keep in touch!"

# Phone number type must be one of 'business', 'organization_main',
# 'mobile', 'assistant', 'business_fax', 'home_fax', 'radio', 'car', 'home', or 'pager'
# Google and Microsoft label 'business' phone numbers as the contact's Work phone number
contact.phone_numbers['business'] = ['(555) 555-5555']

# Web page type must be one of 'homepage', 'profile', 'work', or 'blog'
contact.web_pages['homepage'] = ["https://nylas.com"]

contact.save()
print(contact)
Ready to Build Your Contacts Integration?

Delete a Contact

To delete a contact, you need to get the id of the contact and pass it as an argument to the contacts.delete() function. In the following example, replace CONTACT_ID with the ID of the contact you want to delete.

❗️

You're about to delete a contact!

The next commands will delete the specified! Make sure you want to do this before proceeding.

contact = nylas.contacts.get(CONTACT_ID)
nylas.contacts.delete(contact.id)

Here is the entire code example to delete a contact.

from nylas import APIClient

nylas = APIClient(
    CLIENT_ID,
    CLIENT_SECRET,
    ACCESS_TOKEN,
)

# CONTACT_ID should be the id of the contact object you want to delete.
contact = nylas.contacts.get(CONTACT_ID)

# WARNING: before running this script,
# ensure you want to delete the contact with this designated ID
nylas.contacts.delete(contact.id)
Ready to Build Your Contacts Integration?

Explore the Nylas Contacts API

If you’ve made it this far, congrats, you’ve successfully learned how to manage Google and Microsoft contacts with the Nylas Contacts 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 6 months ago

Google and Microsoft Contacts with Python


Learn how to manage Google & Microsoft contacts with the Nylas Python SDK. Build your contacts book 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.