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 Node.js

The Nylas Node SDK is the quickest way to integrate Google and Microsoft contacts into your app with JavaScript and the Nylas Contacts API. Build your contacts integration in 15 minutes.

Node.js has grown to be the most popular framework in the world, primarily due to its efficiency for data-intensive real-time applications and the ability to use JavaScript across the entire web stack. 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 Node.js 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 Node.js 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.

Setup 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 Node.js SDK

Prerequisites

  • Get Node.js installed on your machine.
  • Make sure you have npm or yarn.

Install the SDK

Head to the nearest command line and run npm install nylas or yarn add nylas.

Congrats! You’re now ready to start using the Nylas Node.js 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. The Nylas object provides access to every resource in the Nylas Contacts API, so the first thing you need to do is to initialize it:

const Nylas = require('nylas');

Then, call the config function and pass the CLIENT_ID and CLIENT_SECRET from earlier in this guide, replacing the placeholders with your values.

Nylas.config({
    clientId: CLIENT_ID,
    clientSecret: CLIENT_SECRET,
});

🚧

Take care with your secrets

It’s not best practice to include secrets like this in your code. For increased security, store these values as environment variables.

Next, call .with() and pass the ACCESS_TOKEN from earlier in this guide to allow Nylas to access data for a specific user account.

const nylas = Nylas.with(ACCESS_TOKEN);

Now you’re ready to try out the code examples in the next sections.

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. To do so, we get a list of contact objects with nylas.contacts.list() and iterate over the list to get the attributes we want for each contact.

nylas.contacts.list({limit: 10}).then(contacts => {
    for (const contact of contacts) {
        console.log(`Name: ${contact.givenName} ${contact.surname} | Email: ${contact.emailAddresses[0]['email']} | ID: ${contact.id}`);
    }
});

This example logs the givenName, surname, and id attributes for each of the contacts. It also provides the first email address for the contact from emailAddresses. emailAddresses returns a list of all email addresses associated with the account along with their types. Take a look at the API reference for the contacts endpoint to learn more about the attributes the contact object contains.

For convenience, here is the entire example to list the first 10 contacts for an account.

const Nylas = require('nylas');
Nylas.config({
    clientId: CLIENT_ID,
    clientSecret: CLIENT_SECRET,
});
const nylas = Nylas.with(ACCESS_TOKEN);
// Log the first and last name, email address, and the ID of the first 10 contacts returned for the user's account
nylas.contacts.list({limit: 10}).then(contacts => {
    for (const contact of contacts) {
        console.log(`Name: ${contact.givenName} ${contact.surname} | Email: ${contact.emailAddresses[0]['email']} | ID: ${contact.id}`);
    }
});
Ready to Build Your Contacts Integration?

Create a Contact

To create a Google contact, use nylas to create a new contact object with .contacts.build(), specifying the attributes you want the new contact to have.

const contact = nylas.contacts.build({
    givenName: "My",
    middleName: "Nylas",
    surname: "Friend",
    notes: "Make sure to keep in touch!",
    emailAddresses: [{type: 'work', email: '[email protected]'}],
    phoneNumbers: [{type: 'business', number: '(555) 555-5555'}],
    webPages: [{type: 'homepage', url: 'nylas.com'}]
});

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

  • givenName middleName, and surname define the contact's first, middle, and last name.
  • emailAddresses adds an email address to the contact and sets the type to work. You can also specify personal as a type.
  • Similarly, phoneNumbers 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, webPages 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 contacts endpoint to learn more about the attributes you can assign to a contact object.

The last thing you need to do is call .save() on the contact object. This saves the contact to Nylas which, in turn, syncs the new contact to Google.

contact.save().then( contact => {
    console.log(contact);
});

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.

const Nylas = require('nylas');
Nylas.config({
    clientId: CLIENT_ID,
    clientSecret: CLIENT_SECRET,
});
const nylas = Nylas.with(ACCESS_TOKEN);

const contact = nylas.contacts.build({
    // Give the contact a first, middle, and last name
    givenName: "My",
    middleName: "Nylas",
    surname: "Friend",
    notes: "Make sure to keep in touch!",

    // Email address 'type' must be either 'work' or 'personal'
    emailAddresses: [{type: 'work', email: '[email protected]'}],

    // Phone number type must be one of 'business', 'organization_main', 
    // 'mobile', 'assistant', 'business_fax', 'home_fax', 'radio', 'car', 'home', or 'pager'
    // Google labels 'business' phone numbers as the contact's Work phone number
    phoneNumbers: [{type: 'business', number: '(555) 555-5555'}],

    // Web page type must be one of 'homepage', 'profile', 'work', or 'blog'
    webPages: [{type: 'homepage', url: 'nylas.com'}]
});

contact.save().then( contact => {
    console.log(contact);
});
Ready to Build Your Contacts Integration?

Delete a Contact

To delete a contact from Google, 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 following code example will delete the specified contact from Google. Make sure you want to do this before proceeding.

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

Here is the entire code example to delete a Google contact.

const Nylas = require('nylas');
Nylas.config({
    clientId: CLIENT_ID,
    clientSecret: CLIENT_SECRET,
});
const nylas = Nylas.with(ACCESS_TOKEN);
// WARNING: Ensure you want to delete the contact with the given ID before running this script.
contact = nylas.contacts.find(CONTACT_ID)
contact = 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 3 months ago

Google and Microsoft Contacts with Node.js


The Nylas Node SDK is the quickest way to integrate Google and Microsoft contacts into your app with JavaScript and the Nylas Contacts API. Build your contacts 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.