Version:
Only show these results:

Using the v2 Contacts API

The Nylas Contacts API allows you to create and manage contacts, and organize them into contact groups. This page introduces the basic functionality of the Contacts API using API requests and other examples. Most examples also include the JSON response, so you don't have to make a query on your own to see the expected response structure.

The examples on this page cover how to use the Contacts API for the following tasks:

  • Viewing contact information.
  • Creating and modifying contacts.
  • Deleting contacts.
  • Handling inconsistencies and limitations between address book providers.

Before you begin

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

View all contacts

The simplest way to view information about your end users' contacts is to make a Get Contacts request.

By default, Nylas returns 100 results. For the purpose of this guide, queries use the limit parameter to return a maximum of 5 contacts. For more information about limits and offsets, see the Pagination reference documentation.

The following example shows how use the Contacts API to view contact information, and the type of response you can expect.

curl -X GET https://{access_token}:@api.nylas.com/contacts?limit=5   
[{
  "account_id": "qmlclekd5d3bgscbhhkf",
  "birthday": "2011-01-01",
  "company_name": "Nylas",
  "emails": [{
    "email": "swag@example.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"
  }]
}]

You can also get contact information using the Nylas SDKs, as in the examples below.

from nylas import APIClient

nylas = APIClient(NYLAS_CLIENT_ID, NYLAS_CLIENT_SECRET, ACCESS_TOKEN)
contacts = nylas.contacts.all(limit=5)

for contact in contacts:
  print(contact)   
const Nylas = require('nylas');

Nylas.config({
  clientId: NYLAS_CLIENT_ID,
  clientSecret: NYLAS_CLIENT_SECRET,
});

const nylas = Nylas.with(ACCESS_TOKEN);

nylas.contacts.list({limit: 5}).then(contacts => {
  for (const contact of contacts) {
    console.log(contact);
  }
});

View a contact

To get information for a specific contact, make a Get Contact request with the contact's ID, as in the example below.

curl -X GET https://{access_token}:@api.nylas.com/contacts/{id}   
[{
  "account_id": "qmlclekd5d3bgscbhhkf",
  "birthday": "2011-01-01",
  "company_name": "Nylas",
  "emails": [{
    "email": "swag@example.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 information Nylas returns, see the Contacts reference documentation.

You can also use the Nylas SDKs to return information about a specific contact, as in the examples below.

from nylas import APIClient

nylas = APIClient(NYLAS_CLIENT_ID, NYLAS_CLIENT_SECRET, ACCESS_TOKEN)
contact = nylas.contacts.get('{id}')

print(contact)   
const Nylas = require('nylas');

Nylas.config({
  clientId: NYLAS_CLIENT_ID,
  clientSecret: NYLAS_CLIENT_SECRET,
});

const nylas = Nylas.with(ACCESS_TOKEN);

nylas.contacts.get("{id}").then(contact => {
  console.log(contact);
});

Download contact profile images

Many service providers allow end users to assign a photo to a contact's profile. You can access contact profile images by making a Return Contact Picture request. Nylas returns a binary data blob that represents the image. To save or display it, you must redirect the response to an appropriate file.

The examples below show how to get a contact's photo and save it as a JPG file using the v2 Contacts API and the Nylas SDKs.

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

nylas = APIClient(NYLAS_CLIENT_ID, NYLAS_CLIENT_SECRET, ACCESS_TOKEN)
contact = nylas.contacts.get(CONTACT_ID)
picture = contact.get_picture()

file = open('picture.jpg', 'w+b"')
file.write(picture.read())
file.close()

print(contact.picture_url)   
const Nylas = require('nylas');

Nylas.config({
  clientId: NYLAS_CLIENT_ID,
  clientSecret: NYLAS_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);

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)

Create a contact

To create a contact, make a POST /contacts request that includes the contact's profile information, as in the following examples.

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

You can also use the Nylas SDKs to create contacts, as in the examples below.

from nylas import APIClient

nylas = APIClient(NYLAS_CLIENT_ID, NYLAS_CLIENT_SECRET, ACCESS_TOKEN)

contact = nylas.contacts.create()
contact.given_name = "My"
contact.middle_name = "Nylas Docs"
contact.surname = "Friend"
contact.emails['work'] = ['ireadthedocs@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');
const { default: Contact } = require('nylas/lib/models/contact');

Nylas.config({
  clientId: NYLAS_CLIENT_ID,
  clientSecret: NYLAS_CLIENT_SECRET,
});

const nylas = Nylas.with(ACCESS_TOKEN);

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

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

Modify a contact

When you create a contact, Nylas responds with an id that represents the contact record, and other information about the contact. You can use this id to modify a specific contact, as in the examples below.

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

For more information, see the Modify Contact reference documentation.

Delete a contact

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

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

You can also use the Nylas SDKs to delete a contact, as in the examples below.

from nylas import APIClient

nylas = APIClient(NYLAS_CLIENT_ID, NYLAS_CLIENT_SECRET, ACCESS_TOKEN)

nylas.contacts.delete('{id}')   
const Nylas = require('nylas');

Nylas.config({
  clientId: NYLAS_CLIENT_ID,
  clientSecret: NYLAS_CLIENT_SECRET,
});

const nylas = Nylas.with(ACCESS_TOKEN);

nylas.contacts.delete('{id}')

Organize contacts with contact groups

Contact groups allow your end users to organize their contacts.

⚠️ Contact groups have different meanings between providers. This affects the way Nylas presents them. See the v2 Contact Groups reference documentation for more information.

You can get a full list of contact groups by making a Get Contact Groups request, as in the following example.

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"
  }
]

Limitations

The following sections describe some limitations that you should keep in mind when working with the Nylas Contacts API.

Parsed versus synced contacts

Nylas creates two types of contacts: parsed and synced. Parsed contacts are created from the end user's email messages and are assigned the source: "inbox" value. Synced contacts are created from the end user's address book and are assigned the source: "address_book" value.

When Nylas provides information about contacts, its responses differ between these sources.

For parsed contacts, Nylas excludes many values from the JSON response, as in the example below.

{
  "account_id": "<ACCOUNT_ID>",
  "birthday": null,
  "company_name": null,
  "emails": [{
    "email": "tips@example.com",
    "type": null
  }],
  "given_name": "Nylas",
  "groups": [],
  "id": "<CONTACT_ID>",
  "im_addresses": [],
  "job_title": null,
  "manager_name": null,
  "middle_name": null,
  "nickname": null,
  "notes": null,
  "object": "contact",
  "office_location": null,
  "phone_numbers": [],
  "physical_addresses": [],
  "picture_url": null,
  "source": "inbox",
  "suffix": null,
  "surname": "Tips",
  "web_pages": []
}

For synced contacts, Nylas includes more information.

{
  "account_id": "<ACCOUNT_ID>",
  "birthday": "1930-01-19",
  "company_name": "Prime Time Primates",
  "emails": [{
    "email": "thedren@example.org",
    "type": "work"
  }],
  "given_name": "Tippi",
  "groups": [{
    "account_id": "<ACCOUNT_ID>",
    "id": "<GROUP_ID>",
    "name": "System Group: My Contacts",
    "object": "contact_group",
    "path": "System Group: My Contacts"
  }],
  "id": "<CONTACT_ID>",
  "im_addresses": [],
  "job_title": "Zoologist",
  "manager_name": null,
  "middle_name": null,
  "nickname": null,
  "notes": null,
  "object": "contact",
  "office_location": null,
  "phone_numbers": [{
    "number": "(218) 301-2284",
    "type": "mobile"
  }],
  "physical_addresses": [{
    "address": "Duluth, MN 55811\nUS",
    "format": "unstructured",
    "type": null
  }],
  "picture_url": "https://api.nylas.com/contacts/<CONTACT_ID>/picture",
  "source": "address_book",
  "suffix": null,
  "surname": "Hedren",
  "web_pages": []
}

Microsoft Exchange limitations

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

  • Phone numbers must have a non-null type. Exchange does not accept phone numbers of the other type.
  • Contacts can have a maximum of two home or business phone numbers.
    • Labels such as business are not supported.
  • Contacts can have a maximum of three email addresses.
    • Email addresses have their type set to null by default. You can change them to be personal or work.
  • Contacts can have a maximum of three instant messenger (IM) addresses.
    • IM addresses have their type set to null by default.
  • Exchange contacts support only the work, home, and other labels for the postal_address parameter.
  • Exchange contacts don't support the web_page and notes parameters.
  • Exchange contacts don't support the other, other fax, callback, telex, and tty/tdd phone types.

Google limitations

  • Google contacts don't support the Google Voice phone type or custom phone types.

Google contact historical sync

Nylas syncs a maximum of 100,000 contacts when an end user authenticates or re-authenticates their Google account. There is no limit to the number of contacts Nylas syncs as long as the account remains connected to your Nylas application, however.

Google contact polling interval

Google doesn't have a modern push notification API to enable real-time notifications of changes to contacts. Because of this, Nylas polls for changes every 60 seconds.

What's next?