Using the Contacts API
💡 Looking for the Contacts API references? You can find them here!
The Nylas Contacts API provides a secure and reliable connection to your end users' contacts. This enables you to perform bi-directional sync with full CRUD (Create, Read, Update, Delete) capabilities for Google and Microsoft accounts. The API provides a REST interface that allows you to do the following tasks:
- Read contact information, including names, email addresses, phone numbers, and more.
- Organize contacts using contact groups.
Contact sources
🔍 There are three contacts sources: the end user's address book (address_book
), their organization's domain (domain
, for example, a Microsoft Active Directory contact list), and the participants from email messages in their inbox (inbox
).
By default, Nylas only looks for contacts in the end user's address book when you make a Get Contacts request. To fetch contacts from either the domain or the end user's inbox, add the ?source=domain
or ?source=inbox
query parameter to your request.
To get contact information from an end user's inbox, you must also have requested the following scopes:
- Google:
contacts.other.readonly
- Microsoft:
People.Read
For more information, see the Contacts scopes documentation.
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.
View all contacts
The simplest way to view information about your end users' contacts is to make a Get Contacts request. By default, the endpoint returns 30 results. For the purpose of this guide, queries use the limit
parameter to return a maximum of five contacts. For more information about limits and offsets, see the pagination reference documentation.
The following examples show how to use the Contacts API and the Nylas SDKs to view contact information.
curl --request GET \
--url https://api.us.nylas.com/v3/grants/<NYLAS_GRANT_ID>/contacts \
--header 'Accept: application/json' \
--header 'Authorization: Bearer <NYLAS_API_KEY>' \
--header 'Content-Type: application/json'
import 'dotenv/config'
import Nylas from 'nylas'
const NylasConfig = {
apiKey: process.env.NYLAS_API_KEY,
apiUri: process.env.NYLAS_API_URI,
}
const nylas = new Nylas(NylasConfig)
async function fetchContacts() {
try {
const identifier = process.env.NYLAS_GRANT_ID
const contacts = await nylas.contacts.list({
identifier,
queryParams: {},
})
console.log('Recent Contacts:', contacts)
} catch (error) {
console.error('Error fetching drafts:', error)
}
}
fetchContacts()
require 'nylas'
nylas = Nylas::Client.new(api_key: "<NYLAS_API_KEY>")
contacts, _ = nylas.contacts.list(identifier: ENV["NYLAS_GRANT_ID"])
contacts.each {|contact|
puts "Name: #{contact[:given_name]} #{contact[:surname]} | " \
"Email: #{contact[:emails][0][:email]} | ID: #{contact[:id]}"
}
import com.nylas.NylasClient;
import com.nylas.models.*;
public class ReadAllContacts {
public static void main(String[] args) throws NylasSdkTimeoutError, NylasApiError {
NylasClient nylas = new NylasClient.Builder("<NYLAS_API_KEY>").build();
ListResponse<Contact> contacts = nylas.contacts().list("<NYLAS_GRANT_ID>");
for(Contact contact : contacts.getData()) {
System.out.println(contact);
System.out.println("\n");
}
}
}
import com.nylas.NylasClient
fun main(args: Array<String>) {
val nylas: NylasClient = NylasClient(apiKey = "<NYLAS_API_KEY>")
val contacts = nylas.contacts().list("<NYLAS_GRANT_ID>")
for(contact in contacts.data){
println(contact)
}
}
View a contact
To get information about a specific contact, make a Get Contact request with the contact's ID, as in the example below.
curl --request GET \
--url https://api.us.nylas.com/v3/grants/<NYLAS_GRANT_ID>/contacts/<CONTACT_ID> \
--header 'Accept: application/json' \
--header 'Authorization: Bearer <NYLAS_API_KEY>' \
--header 'Content-Type: application/json'
To learn more about the information a Contact object contains, see the Contacts reference documentation.
You can also use the Nylas SDKs to return information about a specific contact, as in the examples below.
import 'dotenv/config'
import Nylas from 'nylas'
const NylasConfig = {
apiKey: process.env.NYLAS_API_KEY,
apiUri: process.env.NYLAS_API_URI,
}
const nylas = new Nylas(NylasConfig)
async function fetchContactById() {
try {
const contact = await nylas.contacts.find({
identifier: process.env.NYLAS_GRANT_ID,
contactId: process.env.CONTACT_ID,
queryParams: {},
})
console.log('contact:', contact)
} catch (error) {
console.error('Error fetching contact:', error)
}
}
fetchContactById()
from dotenv import load_dotenv
load_dotenv()
import os
import sys
from nylas import Client
nylas = Client(
os.environ.get('NYLAS_API_KEY'),
os.environ.get('NYLAS_API_URI')
)
grant_id = os.environ.get("NYLAS_GRANT_ID")
contact_id = os.environ.get("CONTACT_ID")
contact = nylas.contacts.find(
grant_id,
contact_id,
)
print(contact)
require 'nylas'
nylas = Nylas::Client.new(api_key: "<NYLAS_API_KEY>")
contact, _ = nylas.contacts.find(identifier: "<NYLAS_GRANT_ID>", contact_id: "<CONTACT_ID>")
puts contact
import com.nylas.NylasClient;
import com.nylas.models.*;
public class ReturnAContact {
public static void main(String[] args) throws NylasSdkTimeoutError, NylasApiError {
NylasClient nylas = new NylasClient.Builder("<NYLAS_API_KEY>").build();
Response<Contact> contact = nylas.contacts().find("<NYLAS_GRANT_ID>", "<CONTACT_ID>");
System.out.println(contact);
}
}
import com.nylas.NylasClient
fun main(args: Array<String>) {
val nylas: NylasClient = NylasClient(apiKey = "<NYLAS_API_KEY>")
var contact = nylas.contacts().find("<NYLAS_GRANT_ID>", "<CONTACT_ID>")
print(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 in Nylas v3 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, you must redirect the response to an appropriate file.
Create a contact
To create a contact, make a POST /v3/grants/<NYLAS_GRANT_ID>/contacts
request. Include the contact's profile information, as in the following example.
curl --request POST \
--url https://api.us.nylas.com/v3/grants/<NYLAS_GRANT_ID>/contacts \
--header 'Accept: application/json' \
--header 'Authorization: Bearer <NYLAS_API_KEY>' \
--header 'Content-Type: application/json' \
--data '{
"birthday": "1960-12-31",
"company_name": "Nylas",
"emails": [
{
"email": "john-work@example.com",
"type": "work"
},
{
"email": "john-home@example.com",
"type": "home"
}
],
"given_name": "John",
"groups": [
{
"id": "starred"
},
{
"id": "all"
}
],
"im_addresses": [
{
"type": "jabber",
"im_address": "myjabberaddress"
},
{
"type": "msn",
"im_address": "mymsnaddress"
}
],
"job_title": "Software Engineer",
"manager_name": "Bill",
"middle_name": "Jacob",
"nickname": "JD",
"notes": "Loves Ramen",
"office_location": "123 Main Street",
"phone_numbers": [
{
"number": "+1-555-555-5555",
"type": "work"
},
{
"number": "+1-555-555-5556",
"type": "home"
}
],
"physical_addresses": [
{
"type": "work",
"street_address": "123 Main Street",
"postal_code": "94107",
"state": "CA",
"country": "USA",
"city": "San Francisco"
},
{
"type": "home",
"street_address": "456 Main Street",
"postal_code": "94107",
"state": "CA",
"country": "USA",
"city": "San Francisco"
}
],
"source": "address_book",
"suffix": "Jr.",
"surname": "Doe",
"web_pages": [
{
"type": "work",
"url": "http://www.linkedin.com/in/johndoe"
},
{
"type": "home",
"url": "http://www.johndoe.com"
}
]
}'
You can also use the Nylas SDKs to create contacts, as in the examples below.
import 'dotenv/config'
import Nylas from 'nylas'
const NylasConfig = {
apiKey: process.env.NYLAS_API_KEY,
apiUri: process.env.NYLAS_API_URI,
}
const nylas = new Nylas(NylasConfig)
async function createContact() {
try {
const contact = await nylas.contacts.create({
identifier: process.env.NYLAS_GRANT_ID,
requestBody: {
givenName: "My",
middleName: "Nylas",
surname: "Friend",
notes: "Make sure to keep in touch!",
emails: [{type: 'work', email: 'swag@example.com'}],
phoneNumbers: [{type: 'work', number: '(555) 555-5555'}],
webPages: [{type: 'other', url: 'nylas.com'}]
}
})
console.log('Contact:', JSON.stringify(contact))
} catch (error) {
console.error('Error to create contact:', error)
}
}
createContact()
from dotenv import load_dotenv
load_dotenv()
import os
import sys
from nylas import Client
nylas = Client(
os.environ.get('NYLAS_API_KEY'),
os.environ.get('NYLAS_API_URI')
)
grant_id = os.environ.get("NYLAS_GRANT_ID")
contact = nylas.contacts.create(
grant_id,
request_body={
"middleName": "Nylas",
"surname": "Friend",
"notes": "Make sure to keep in touch!",
"emails": [{"type": "work", "email": "swag@example.com"}],
"phoneNumbers": [{"type": "work", "number": "(555) 555-5555"}],
"webPages": [{"type": "other", "url": "nylas.com"}]
}
)
print(contact)
require 'nylas'
nylas = Nylas::Client.new(api_key: "<NYLAS_API_KEY>")
request_body = {
given_name: "My",
middle_name: "Nylas",
surname: "Friend",
emails: [{email: "nylas-friend@example.com", type: "work"}],
notes: "Make sure to keep in touch!",
phone_numbers: [{number: "555 555-5555", type: "business"}],
web_pages: [{url: "https://www.nylas.com", type: "homepage"}]
}
contact, _ = nylas.contacts.create(identifier: "<NYLAS_GRANT_ID>", request_body: request_body)
puts contact
import com.nylas.NylasClient;
import com.nylas.models.*;
import java.util.ArrayList;
import java.util.List;
public class CreateAContact {
public static void main(String[] args) throws
NylasSdkTimeoutError, NylasApiError {
NylasClient nylas = new NylasClient.Builder("<NYLAS_API_KEY>").build();
List<ContactEmail> contactEmails = new ArrayList<>();
contactEmails.add(new ContactEmail("swag@nylas.com", "work"));
List<WebPage> contactWebpages = new ArrayList<>();
contactWebpages.add(new WebPage("https://www.nylas.com", "work"));
CreateContactRequest requestBody = new CreateContactRequest.Builder().
emails(contactEmails).
companyName("Nylas").
givenName("Nylas' Swag").
notes("This is good swag").
webPages(contactWebpages).
build();
Response<Contact> contact = nylas.contacts().create("<NYLAS_GRANT_ID>", requestBody);
System.out.println(contact);
}
}
import com.nylas.NylasClient
import com.nylas.models.ContactEmail
import com.nylas.models.ContactType
import com.nylas.models.CreateContactRequest
import com.nylas.models.WebPage
fun main(args: Array<String>) {
val nylas: NylasClient = NylasClient(apiKey = "<NYLAS_API_KEY>")
val emails : List<ContactEmail> = listOf(ContactEmail("swag@nylas.com", "work"))
val webpage : List<WebPage> = listOf(WebPage("https://www.nylas.com", "work"))
val contactRequest = CreateContactRequest.Builder().
emails(emails).
companyName("Nylas").
givenName("Nylas' Swag").
notes("This is good swag").
webPages(webpage).
build()
val contact = nylas.contacts().create("<NYLAS_GRANT_ID>", contactRequest)
print(contact.data)
}
Modify a contact
When you create a contact, Nylas responds with an id
that represents the contact record, along with other information about the contact. You can use this id
to modify a specific contact, as in the examples below.
curl --request PUT \
--url https://api.us.nylas.com/v3/grants/<NYLAS_GRANT_ID>/contacts/<CONTACT_ID> \
--header 'Accept: application/json' \
--header 'Authorization: Bearer <NYLAS_API_KEY>' \
--header 'Content-Type: application/json' \
--data '{
"birthday": "1960-12-31",
"company_name": "Nylas",
"emails": [
{
"email": "john-work@example.com",
"type": "work"
},
{
"email": "john-home@example.com",
"type": "home"
}
],
"given_name": "John",
"groups": [
{
"id": "starred"
},
{
"id": "all"
}
],
"im_addresses": [
{
"type": "jabber",
"im_address": "myjabberaddress"
},
{
"type": "msn",
"im_address": "mymsnaddress"
}
],
"job_title": "Software Engineer",
"manager_name": "Bill",
"middle_name": "Jacob",
"nickname": "JD",
"notes": "Loves Ramen",
"office_location": "123 Main Street",
"phone_numbers": [
{
"number": "+1-555-555-5555",
"type": "work"
},
{
"number": "+1-555-555-5556",
"type": "home"
}
],
"physical_addresses": [
{
"type": "work",
"street_address": "123 Main Street",
"postal_code": "94107",
"state": "CA",
"country": "USA",
"city": "San Francisco"
},
{
"type": "home",
"street_address": "456 Main Street",
"postal_code": "94107",
"state": "CA",
"country": "USA",
"city": "San Francisco"
}
],
"source": "address_book",
"suffix": "Jr.",
"surname": "Doe",
"web_pages": [
{
"type": "work",
"url": "http://www.linkedin.com/in/johndoe"
},
{
"type": "home",
"url": "http://www.johndoe.com"
}
]
}'
import 'dotenv/config'
import Nylas from 'nylas'
const NylasConfig = {
apiKey: process.env.NYLAS_API_KEY,
apiUri: process.env.NYLAS_API_URI,
}
const nylas = new Nylas(NylasConfig)
async function updateContact() {
try {
const contact = await nylas.contacts.update({
identifier: process.env.NYLAS_GRANT_ID,
contactId: process.env.CONTACT_ID,
requestBody: {
givenName: "Nyla",
}
})
console.log('Contact:', JSON.stringify(contact))
} catch (error) {
console.error('Error to create contact:', error)
}
}
updateContact()
from dotenv import load_dotenv
load_dotenv()
import os
import sys
from nylas import Client
nylas = Client(
os.environ.get('NYLAS_API_KEY'),
os.environ.get('NYLAS_API_URI')
)
grant_id = os.environ.get("NYLAS_GRANT_ID")
contact_id = os.environ.get("CONTACT_ID")
contact = nylas.contacts.update(
grant_id,
contact_id,
request_body={
"given_name": "Nyla",
}
)
print(contact)
require 'nylas'
nylas = Nylas::Client.new(api_key: "<NYLAS_API_KEY>")
request_body = {
notes: "This is *the best* swag",
}
contact, _ = nylas.contacts.update(identifier: "<NYLAS_GRANT_ID>",
contact_id: "<CONTACT_ID>",
request_body: request_body)
puts contact
import com.nylas.NylasClient;
import com.nylas.models.*;
public class UpdateContact {
public static void main(String[] args) throws NylasSdkTimeoutError, NylasApiError {
NylasClient nylas = new NylasClient.Builder("<NYLAS_API_KEY>").build();
UpdateContactRequest requestBody = new UpdateContactRequest.
Builder().
notes("This is *the best* swag").
build();
Response<Contact> contact = nylas.contacts().update("<NYLAS_GRANT_ID>", "<CONTACT_ID>", requestBody);
System.out.println(contact);
}
}
import com.nylas.NylasClient
import com.nylas.models.*
fun main(args: Array<String>) {
val nylas: NylasClient = NylasClient(apiKey = "<NYLAS_API_KEY>")
val updateRequest = UpdateContactRequest.Builder().
notes("This is *the best* swag").
build()
val contact = nylas.contacts().update("<NYLAS_GRANT_ID>", "<CONTACT_ID>", updateRequest)
print(contact.data)
}
For more information, see the Update Contact reference documentation.
Delete a contact
To delete a contact, make a Delete Contact request with the contact's id
, or use the Nylas SDKs.
curl --request DELETE \
--url https://api.us.nylas.com/v3/grants/<NYLAS_GRANT_ID>/contacts/<CONTACT_ID> \
--header 'Accept: application/json' \
--header 'Authorization: Bearer <NYLAS_API_KEY>' \
--header 'Content-Type: application/json'
import 'dotenv/config'
import Nylas from 'nylas'
const NylasConfig = {
apiKey: process.env.NYLAS_API_KEY,
apiUri: process.env.NYLAS_API_URI,
}
const nylas = new Nylas(NylasConfig)
const identifier = process.env.NYLAS_GRANT_ID
const contactId = process.env.CONTACT_ID
const deleteContact = async () => {
try {
await nylas.contacts.destroy({ identifier, contactId })
console.log(`Contact with ID ${contactId} deleted successfully.`)
} catch (error) {
console.error(`Error deleting contact with ID ${contactId}:`, error)
}
}
deleteContact()
from dotenv import load_dotenv
load_dotenv()
import os
import sys
from nylas import Client
nylas = Client(
os.environ.get('NYLAS_API_KEY'),
os.environ.get('NYLAS_API_URI')
)
grant_id = os.environ.get("NYLAS_GRANT_ID")
contact_id = os.environ.get("CONTACT_ID")
request = nylas.contacts.destroy(
grant_id,
contact_id,
)
print(request)
require 'nylas'
nylas = Nylas::Client.new(api_key: "<NYLAS_API_KEY>")
status, _ = nylas.contacts.destroy(identifier: "<NYLAS_GRANT_ID>", contact_id: "<CONTACT_ID>")
puts status
import com.nylas.NylasClient;
import com.nylas.models.*;
public class DeleteAContact {
public static void main(String[] args) throws NylasSdkTimeoutError, NylasApiError {
NylasClient nylas = new NylasClient.Builder("<NYLAS_API_KEY>").build();
DeleteResponse contact = nylas.contacts().destroy("<NYLAS_GRANT_ID>", "<CONTACT_ID>");
System.out.println(contact);
}
}
import com.nylas.NylasClient
import io.github.cdimascio.dotenv.dotenv
fun main(args: Array<String>) {
val dotenv = dotenv()
val nylas: NylasClient = NylasClient(apiKey = dotenv["NYLAS_API_KEY"])
var contact = nylas.contacts().destroy(dotenv["NYLAS_GRANT_ID"], "c5895840358462569130")
print(contact)
}
Organize contacts with contact groups
Contact groups allow your end users to organize their contacts. You can get a full list of an end user's contact groups by making a Get Contact Groups request, or by using the Nylas SDKs.
curl --request GET \
--url https://api.us.nylas.com/v3/grants/<NYLAS_GRANT_ID>/contacts/groups \
--header 'Accept: application/json' \
--header 'Authorization: Bearer <NYLAS_API_KEY>' \
--header 'Content-Type: application/json'
import 'dotenv/config'
import Nylas from 'nylas'
const NylasConfig = {
apiKey: process.env.NYLAS_API_KEY,
apiUri: process.env.NYLAS_API_URI,
}
const nylas = new Nylas(NylasConfig)
async function fetchContactGroups() {
try {
const identifier = process.env.NYLAS_GRANT_ID
const contactGroups = await nylas.contacts.groups({
identifier,
})
console.log('Contacts Groups:', contactGroups)
} catch (error) {
console.error('Error fetching contact groups:', error)
}
}
fetchContactGroups()
from dotenv import load_dotenv
load_dotenv()
import os
import sys
from nylas import Client
nylas = Client(
os.environ.get('NYLAS_API_KEY'),
os.environ.get('NYLAS_API_URI')
)
grant_id = os.environ.get("NYLAS_GRANT_ID")
contact_groups = nylas.contacts.list_groups(
grant_id,
)
print(contact_groups)
require 'nylas'
nylas = Nylas::Client.new(api_key: "<NYLAS_API_KEY>")
groups = nylas.contacts.list_groups(identifier: "<NYLAS_GRANT_ID>")
puts groups
import com.nylas.NylasClient;
import com.nylas.models.*;
public class ReadContactGroups {
public static void main(String[] args) throws NylasSdkTimeoutError, NylasApiError {
NylasClient nylas = new NylasClient.Builder("<NYLAS_API_KEY>").build();
ListResponse<ContactGroup> groups = nylas.contacts().listGroups("<NYLAS_GRANT_ID>");
System.out.println(groups);
}
}
import com.nylas.NylasClient
import io.github.cdimascio.dotenv.dotenv
fun main(args: Array<String>) {
val dotenv = dotenv()
val nylas: NylasClient = NylasClient(apiKey = dotenv["NYLAS_API_KEY"])
var groups = nylas.contacts().listGroups(dotenv["NYLAS_GRANT_ID"])
print(groups)
}
Limitations of the Contacts API
The following sections describe some limitations you should keep in mind when working with the Nylas Contacts API.
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 theother
type. - Contacts can have a maximum of two
home
andbusiness
phone numbers.- Labels such as
business
are not supported.
- Labels such as
- Contacts can have a maximum of three email addresses.
- Email addresses must have their type set to
null
by default. You can manually change them to bepersonal
orwork
.
- Email addresses must have their type set to
- Contacts can have a maximum of three instant messenger (IM) addresses.
- IM addresses have their type set to
null
by default.
- IM addresses have their type set to
- Exchange contacts support only the
work
,home
, andother
labels for thepostal_address
. - Exchange contacts don't support the
other
,other fax
,callback
,telex
, andtty/tdd
phone types.
Google limitations
Nylas applies the following limitations to Google contacts:
- Google contacts don't support the
Google Voice
phone type, or custom phone types.
Historical sync for Google contacts
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 that Nylas syncs, as long as the account remains connected to your Nylas application.
Polling interval for Google contacts
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?
Now that you know how to work with the Nylas Contacts API, you can read the following blog posts to dive deeper: