Skip to content

Using the Contacts API

The Nylas Contacts API provides a secure and reliable connection to your users’ contacts. This enables you to perform bi-directional sync with full CRUD (Create, Read, Update, Delete) capabilities for users’ accounts. The API provides a REST interface that lets you…

  • Read contact information, including names, email addresses, phone numbers, and more.
  • Organize contacts using contact groups.

Contact sources

By default, Nylas only fetches contacts in a user’s address book when you make a Get all Contacts request. To fetch contacts from either the domain or the user’s inbox, add the source query parameter to your request and set it to either domain or inbox.

To get contact information from a user’s inbox, you need the following scopes:

  • Google: contacts.other.readonly
  • Microsoft: People.Read

Before you begin

To follow along with the samples on this page, you first need to sign up for a Nylas developer account, which gets you a free Nylas application and API key.

For a guided introduction, you can follow the Getting started guide to set up a Nylas account and Sandbox application. When you have those, you can connect an account from a calendar provider (such as Google, Microsoft, or iCloud) and use your API key with the sample API calls on this page to access that account’s data.

Return all contacts

To get a list of your user’s contacts, make a Get all Contacts request. By default, Nylas returns up to 30 results. The examples below use the limit parameter to set the maximum number of objects to 5. For more information about limits and offsets, see the pagination references.

View a contact

To get information about a specific contact, make a Get Contact request with the contact’s ID.

Download contact profile image

Many providers let users assign a photo to a contact’s profile. You can access contact profile images by including the ?profile_picture=true query parameter in a Get Contact request.

Nylas returns a Base64-encoded data blob that represents the profile image. To save or display the image, redirect the response to an appropriate file.

Create a contact

To create a contact, make a Create Contact request that includes the contact’s profile information.

Modify a contact

Make an Update Contact request with the contact id to change a contact’s details.

Delete a contact

To delete a contact, make a Delete Contact request with the contact’s id.

Organize contacts with contact groups

Contact groups let your users organize their contacts. You can get a full list of a user’s contact groups by making a Get Contact Groups request.

Contacts limitations

Keep the following limitations in mind as you work with the Contacts API.

Google limitations

Google doesn’t have a modern push notification API to handle real-time changes to contacts, so Nylas polls for changes every 5 minutes.

Microsoft Graph limitations

  • Nylas doesn’t support the other type for phone numbers.
  • Contacts can have only one mobile phone number.
  • Contacts can have up to three email addresses.
    • Email addresses have their type set to null by default.
  • Contacts can have only one work, home, and other physical address.
  • Contacts can have only one work webpage.

Microsoft Exchange limitations

Because of the way the Microsoft Exchange protocol works, Nylas applies the following limitations to Exchange contacts:

  • Nylas doesn’t support the mobile label for phone numbers on Exchange contacts.
  • Nylas doesn’t support adding contacts on Microsoft Exchange accounts to contact groups.
  • Nylas doesn’t support the suffix property on Exchange contacts.
  • Contacts can have up to three email addresses.
    • Email addresses have their type set to null by default.
  • Contacts can have a maximum of three instant messenger (IM) addresses.
    • IM addresses have their type set to null by default.
  • Contacts can have only one work webpage.