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

Contacts API

Explore the Nylas Contacts API

Nylas Contacts API Quickstart Guide

The Nylas Contacts API powers your application with a secure, reliable connection to your user’s contacts. Contact details update in real-time, so your users always have the most recent, accurate data. Get bi-directional contacts sync and full CRUD (create, read, update, delete) capabilities from Google Contacts, Microsoft Exchange Contacts, iCloud, Outlook.com contacts and the rest with just a few lines of code.

The Nylas Contacts API provides a REST interface that includes functionality to

  • Read data for a user’s contacts including name, email, phone number, notes, and more.
  • Create new contacts and modify existing contacts.

Endpoints

This section covers all of the endpoints the Nylas Contacts API provides to enable you to integrate full contacts book functionality into your app.

Contacts

The Contacts endpoint provides access to the user's contacts, making it easy to add contact autocomplete, address book integration, and more to your application.

Other Features of the Nylas Contacts API

The Nylas Communications Platform provides other functionality that makes it easy for you to build your contacts integration.
Filtering allow you to narrow requests based on specific parameters like email or street address, phone numbers, and location. Filters help you reduce the size of your API requests, resulting in faster performance.
Pagination makes it possible to control the number of results that are returned.
Webhooks allow your application to receive notifications when contacts are created, updated, or deleted.
Deltas enable you to process new data quickly without fetching an index of the user's contacts book or performing a large number of API calls.

Quickstart Examples

This section contains examples that demonstrate basic functionality of the Nylas Contacts API; some include examples of a JSON response so you can see what they return, but if you would like to try these examples yourself, complete the developer API keys ) guide before proceeding.

The examples is this sections will demonstrate how to use the Nylas Contacts API to

  • view contact information,
  • create and modify contacts,
  • delete contacts, and
  • handle inconsistencies and limitations between contact book providers.

View Contact Information

The simplest way to view information about a user's contacts is to use the contacts endpoint. By default, the contacts endpoint provides 100 results, but for the purpose of this guide, we will use a query parameter to limit it to 5 contacts. Refer to the docs on pagination to learn about how to use limits and offsets to control the number of objects that are returned. The following examples demonstrate how to view contact information with Nylas.

curl -X GET https://{access_token}:@api.nylas.com/contacts?limit=5
from nylas import APIClient

nylas = APIClient(
    CLIENT_ID,
    CLIENT_SECRET,
    ACCESS_TOKEN,
)

contacts = nylas.contacts.all(limit=5)
for contact in contacts:
  print(contact)
const Nylas = require('nylas');
Nylas.config({
    clientId: CLIENT_ID,
    clientSecret: CLIENT_SECRET,
});
const nylas = Nylas.with(ACCESS_TOKEN);

nylas.contacts.list({limit: 5}).then(contacts => {
    for (const contact of contacts) {
        console.log(contact);
    }
});
[
    {
        "account_id": "qmlclekd5d3bgscbhhkf",
        "birthday": "2011-01-01",
        "company_name": "Nylas",
        "emails": [
            {
                "email": "swag@nylas.com",
                "type": "work"
            }
        ],
        "id": "j2zpf8cju20cmzj64uj6",
        "im_addresses": [
            {
                "im_address": "myaimaddress",
                "type": "aim"
            }
        ],
        "job_title": "Communications Platform",
        "manager_name": "",
	"given_name": "My",
        "middle_name": "Nylas",
	"surname": "Friend",
        "nickname": "Nylas",
        "notes": "Try the Nylas Communications Platform",
        "object": "contact",
        "office_location": "San Francisco, Denver, New York",
        "phone_numbers": [
            {
                "number": "1 800 123 4567",
                "type": "business"
            }
        ],
        "physical_addresses": [],
        "picture_url": "https://api.nylas.com/contacts/p9zyvfxshihbkpyzeyqm/picture",
        "suffix": "Jr.",
        "web_pages": [],
        "groups": [
            {
                "id": "w2kh2bfjvzsgfpkb3b0t",
                "object": "contact_group",
                "account_id": "qmlclekd5d3bgscbhhkf",
                "name": "Work",
                "path": "Contacts/Work"
            }
        ]
    }
]

The information this command provides includes an id value for each contact; you will need one of these ids for the next command. To get information for a specific contact, make a GET request to the contacts/{id} endpoint. In the following example, replace {id} with the id of a contact you want to view.

curl -X GET https://{access_token}:@api.nylas.com/contacts/{id}
from nylas import APIClient

nylas = APIClient(
    CLIENT_ID,
    CLIENT_SECRET,
    ACCESS_TOKEN,
)

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

nylas.contacts.get("{id}").then(contact => {
    console.log(contact);
});
[
    {
        "account_id": "qmlclekd5d3bgscbhhkf",
        "birthday": "2011-01-01",
        "company_name": "Nylas",
        "emails": [
            {
                "email": "swag@nylas.com",
                "type": "work"
            }
        ],
        "id": "j2zpf8cju20cmzj64uj6",
        "im_addresses": [
            {
                "im_address": "myaimaddress",
                "type": "aim"
            }
        ],
        "job_title": "Communications Platform",
        "manager_name": "",
	"given_name": "My",
        "middle_name": "Nylas",
	"surname": "Friend",
        "nickname": "Nylas",
        "notes": "Try the Nylas Communications Platform",
        "object": "contact",
        "office_location": "San Francisco, Denver, New York",
        "phone_numbers": [
            {
                "number": "1 800 123 4567",
                "type": "business"
            }
        ],
        "physical_addresses": [],
        "picture_url": "https://api.nylas.com/contacts/p9zyvfxshihbkpyzeyqm/picture",
        "suffix": "Jr.",
        "web_pages": [],
        "groups": [
            {
                "id": "w2kh2bfjvzsgfpkb3b0t",
                "object": "contact_group",
                "account_id": "qmlclekd5d3bgscbhhkf",
                "name": "Work",
                "path": "Contacts/Work"
            }
        ]
    }
]

To learn more about the values a contact object returns, check out the API reference docs.

Contact Profile Images

Many service providers include a profile picture with contact profiles. This data can be accessed using the contacts/{id}/picture endpoint. When you make a GET request to this endpoint it will return a binary data blob of the image. To save or display the image, redirect the response to an appropriate file. In the following examples, it's saved as a jpg file.

curl -X GET https://{access_token}:@api.nylas.com/contacts/{id}/picture > picture.jpg
from nylas import APIClient

nylas = APIClient(
    CLIENT_ID,
    CLIENT_SECRET,
    ACCESS_TOKEN,
)

contact = nylas.contacts.get(CONTACT_ID)

picture = contact.get_picture()

# Here's an example that shows how to save the picture to a file
file = open('picture.jpg', 'w+b"')
file.write(picture.read())
file.close()

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

let contact;
nylas.contacts.find('{id}').then(resp => contact = resp);

let picture;
contact.getPicture().then(resp => picture = resp);

// Here's an example that shows how to save the picture to a file
const fs = require('fs');
fs.writeFile('picture.jpg', picture, 'binary', (err) => {
  if (err) throw err;
  console.log('The picture was saved!');
});

console.log(contact.pictureUrl)

You can now view picture.jpg with any photo viewing software.

Contact Groups

Contact groups provide a way for users to organize their contacts. You can get a list of contact groups by sending a GET request to the /contacts/groups endpoint.

curl -X GET https://{access_token}:@api.nylas.com/contacts/groups
[
    {
        "id": "a0a0a0a0a0a0a0a0a0a0a0",
        "object": "contact_group",
        "account_id": "x2x2x2x2x2x2x2x2x2x2x2",
        "name": "Work",
        "path": "Contacts/Work"
    },
    {
        "id": "b1b1b1b1b1b1b1b1b1b1b1",
        "object": "contact_group",
        "account_id": "x2x2x2x2x2x2x2x2x2x2x2",
        "name": "Personal",
        "path": "Contacts/Personal"
    }
]

Contact Group Discrepancies

Contact groups have different meanings across different providers. This affects the way contact groups are presented through the Nylas API. Review the API reference for contacts groups for more information about these discrepancies.

Ready to Build Your Contacts Integration?

Create and Modify Contacts

To create a contact, make a POST request to the contacts endpoint with the profile information you want the contact to have. These examples create a new contact and assigns values to some of its attributes.

curl -X POST \
  https://{access_token}:@api.nylas.com/contacts \
  -d '{
    "given_name": "My",
    "middle_name": "Nylas",
    "surname": "Friend"
}'
from nylas import APIClient

nylas = APIClient(
    CLIENT_ID,
    CLIENT_SECRET,
    ACCESS_TOKEN,
)

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

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

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

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

When you execute these examples, they will respond with, among other objects, an id; this can be used to make updates to the contact. If you need to modify a contact, make a PUT request to contacts/{id}.

curl -X PUT \
  https://{access_token}:@api.nylas.com/contacts/{id} \
  -d '{
    "emails": [
        {
        "email": "swag@nylas.com",
        "type": "work"
        }
    ]
}

Finally, to delete a contact, make a DELETE request to the contacts/{id} endpoint.

curl -X DELETE https://{access_token}:@api.nylas.com/contacts/{id}
from nylas import APIClient

nylas = APIClient(
    CLIENT_ID,
    CLIENT_SECRET,
    ACCESS_TOKEN,
)

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

nylas.contacts.delete('{id}')
Ready to Build Your Contacts Integration?

Contacts API Limitations

There are some provider-specific limitations that you should be aware of when working with the Nylas Contacts API.

Next Steps

How Nylas Works - Take a look at the Nylas architecture to see how we enable you to build your contacts book integration.

Quickstart Guides - Get up to speed quickly with our SDKs using our quickstart guides for Python and Node.js, or explore the Nylas Email or Calendar API.

Tutorials - Check out our plethora of tutorials to learn how to carry out common email, calendar, and contacts functionality.

Integration Guides - Ready to start building your integration? Our integration guides cover what it takes to incorporate contacts functionality into your app. They cover best practices for using the Nylas Communications Platform and provider-specific advice for Google, Microsoft, and more.

Set up Postman - Postman makes it easy to explore the Nylas Contacts API.

API Reference - Our API reference provides all the detail you need to know to use the Nylas Communications Platform.

Contacts API


Explore the Nylas Contacts API

Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.