Manage contacts with the Nylas Node.js SDK
The Nylas Node.js SDK is the quickest way to integrate Google and Microsoft (Exchange, Outlook, Office365) contacts into your app with JavaScript and the Nylas Contacts API. The Contacts API makes it simple to create and modify contacts for your users' Google and Microsoft accounts.
This page discusses how to manage Google and Microsoft contacts with the Nylas Node.js SDK and Contacts API. A Contact can include basic information (for example, names and email addresses) and extended information (for example, notes and websites).
What you'll learn
In this tutorial, you'll learn how to do the following tasks:
- Read Contacts from an account's contact list.
- Create and save Google and Microsoft contacts.
- Delete Contacts.
Prerequisites
Before you start, install the Nylas Node.js SDK and set up your environment:
Step 1: Initialize the Nylas
object
At its core, the Nylas platform is an API client that interfaces with all major contact providers.
The Nylas
object provides access to every resource in the Nylas API. Before you make any API requests, you must initialize the Nylas
object with your client ID, client secret, and access token:
- Call the
.config()
function and pass your<CLIENT_ID>
and<CLIENT_SECRET>
. - Call the
.with()
function and pass your<ACCESS_TOKEN>
.
All together, your code should look like the example below.
const Nylas = require('nylas');
Nylas.config({
clientId: <CLIENT_ID>,
clientSecret: <CLIENT_SECRET>
});
const nylas = Nylas.with(<ACCESS_TOKEN>);
Step 2: (Optional) Change the base API URL
You can choose to change the base API URL depending on your location:
Location | API URL | Scheduler API URL |
---|---|---|
United States (Oregon) | https://api.nylas.com |
https://api.schedule.nylas.com |
Europe (Ireland) | https://ireland.api.nylas.com |
https://ireland.api.schedule.nylas.com |
For more information, see Data residency and Migration guide for data centers.
If you're using the Node.js SDK v6.x and the Nylas API v3 Beta: The EU region is currently not available.
To change the API URL, pass the API_URL
parameter to Nylas.config()
:
const Nylas = require('nylas');
Nylas.config({
clientId: <CLIENT_ID>,
clientSecret: <CLIENT_SECRET>,
apiServer: regionConfig[Region.Ireland].nylasAPIUrl
});
const nylas = Nylas.with(<ACCESS_TOKEN>);
If you're using the Nylas EU region: The base API URL defaults to the US region, but you can specify apiServer: regionConfig[Region.Ireland].nylasAPIUrl
to use the EU region. See Data Residency for more information.
Step 3: Read contacts
You can use the nylas.contacts
object to read contacts from an end user's account:
-
Call the
.list()
function to return all contacts. -
(Optional) Specify attributes for the Contact object.
Learn More
For information on available attributes, see the GET /contacts documentation.
The example below reads the first and last names, email addresses, and IDs for the first ten contacts in the account.
const Nylas = require('nylas');
Nylas.config({
clientId: CLIENT_ID,
clientSecret: CLIENT_SECRET,
});
const nylas = Nylas.with(ACCESS_TOKEN);
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}`);
}
});
Step 4: Create and save a contact
After you read contacts from a user's account, you can create and save a contact. The following example creates a new Google Contact object and assigns its attributes.
const { default: Contact } = require('nylas/lib/models/contact');
const contact = new Contact(nylas, {
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'}]
});
- The
givenName
,middleName
, andsurname
parameters define the contact's first, middle, and last name, respectively. - The
notes
parameter adds a note to the contact. emailAddresses
adds an email address to the contact and sets itstype
(work
,personal
, orother
).phoneNumbers
adds a phone number to the contact and sets itstype
(business
,home
,mobile
,page
,business_fax
,home_fax
,organization_main
,assistant
,radio
, orother
). Google and Microsoft label anybusiness
-type phone numbers as the contact’s work phone number.- The
webPages
parameter associates a website URL with the contact and sets itstype
(homepage
,profile
,work
, orblog
).
For information on available attributes, see the POST /contacts documentation.
Next, use the .save()
function to save the contact to Nylas, as in the code snippet below. Nylas then syncs the contact to the user's service provider.
contact.save().then(contact => {
console.log(contact);
});
Example: Create and save a contact
This example creates and saves a contact called "My Nylas Friend".
const Nylas = require('nylas');
const { default: Contact } = require('nylas/lib/models/contact');
Nylas.config({
clientId: CLIENT_ID,
clientSecret: CLIENT_SECRET,
});
const nylas = Nylas.with(ACCESS_TOKEN);
const contact = new Contact(nylas, {
// Define the first, middle, and last name.
givenName: "My",
middleName: "Nylas",
surname: "Friend",
notes: "Make sure to keep in touch!",
// Add the contact's email address.
emailAddresses: [{type: 'work', email: '[email protected]'}],
// Add the contact's phone number.
phoneNumbers: [{type: 'business', number: '(555) 555-5555'}],
// Add the contact's webpage.
webPages: [{type: 'homepage', url: 'nylas.com'}]
});
contact.save().then(contact => {
console.log(contact);
});
When you create a contact for a Google account, it looks like this:

For Microsoft Outlook, the new contact looks like this:

Step 5: Delete a contact
To delete a contact from an end user's account, you must get the contact's id
and pass it as an argument to the contacts.delete()
function. You can use the same endpoint that you used in Step 3 to retrieve the contact ID.
Example: Delete a contact
The next commands delete the contact you specify! Make sure the contact is one you actually want to delete.
The code below finds and deletes a specific contact from an end user's account.
const Nylas = require('nylas');
Nylas.config({
clientId: CLIENT_ID,
clientSecret: CLIENT_SECRET,
});
const nylas = Nylas.with(ACCESS_TOKEN);
contact = nylas.contacts.find(CONTACT_ID)
contact = nylas.contacts.delete(contact.id)
More resources
If you’ve made it this far, congrats! You’ve successfully learned how to manage contacts with the Nylas Contacts API! 🎉
There's plenty more that you can do with Nylas. Take a look at these resources:
- Follow our Node.js SDK tutorials.
- Learn more about the Nylas API.
- Learn more about the Nylas Contacts API.
- Learn more about how the Nylas platform works.
- Read the How to manage contacts with Nylas Node.js SDK blog post.