Only show these results:

Contacts API Guide

This article 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 in this section 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": "[email protected]",
                "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.contacts.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": "[email protected]",
                "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.

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'] = ['[email protected]']
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: CLIENT_ID,
    clientSecret: CLIENT_SECRET,
});
const nylas = Nylas.with(ACCESS_TOKEN);

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'}]
});

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": "[email protected]",
        "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}')

Contacts API Limitations

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

Parsed vs Synced Contacts

Parsed contacts are created from email contacts. Synced contacts are from a user's address book. When Nylas provides information about contacts, responses differ between these two sources.

The source object in the response has two enum values. Parsed contacts have the value inbox and synced contacts result in address_book.

Parsed from inbox

With parsed contacts, many values aren't included in the response after the API request.

   {
       "account_id": "<ACCOUNT_ID>",
       "birthday": null,
       "company_name": null,
       "emails": [
           {
               "email": "[email protected]",
               "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": []
   }

Synced from address_book

Synced contacts from the address_book include more information about the contact.

   {
       "account_id": "<ACCOUNT_ID>",
       "birthday": "1930-01-19",
       "company_name": "Prime Time Primates",
       "emails": [
           {
               "email": "[email protected]",
               "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": []
   }

Exchange

Because of the way the Exchange protocol works, we unfortunately have to restrict Exchange contacts to these arbitrary limits:

  • Exchange contact phone numbers must have a non-null type. Exchange does not accept phone numbers of the other type.
  • Exchange contacts can only have one or two home or business phone numbers.
    • Labels such as business are not supported.
  • Exchange contacts only support three different email addresses. These addresses will have a type set to null by default, but you can change them to be work or personal.
  • Exchange contacts only support three different IM addresses. These addresses will have a type set to null by default.
  • Exchange contacts only support a single web page. This webpage will have a type set to null by default.
  • Exchange contacts do not have support for the notes field.
  • For the postal address field, only work, home, and other labels are supported.

Google Limitations

Contact Historical Sync

Nylas only syncs up to 100,000 contacts when you first authenticate a Google account or when you reconnect a Google account that has been inactive. However, there is no limit to the number of contacts Nylas will sync as long as the account remains connected to your Nylas integration.

Google Contact Polling Interval

Google doesn't have a modern push notification API, to enable realtime notifications of changes to contacts. For this reason, Nylas polls for changes every 60 seconds. You should expect changes to contacts to sync through our system within this timeframe.

Unsupported Phone Types

Google Contacts

  • Google Voice
  • Custom phone types

Exchange Contacts

  • Other
  • Other fax
  • Callback
  • Telex
  • tty/tdd

What's Next?