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 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

Nylas recognizes three sources for contacts: the user’s address book (address_book), their organization’s domain (domain), and the participants from messages in their inbox (inbox).

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.

RequestResponse (JSON)Node.js SDKPython SDKRuby SDKKotlin SDKJava SDK

curl --request GET \
  --url 'https://api.us.nylas.com/v3/grants/<NYLAS_GRANT_ID>/contacts' \
  --header 'Accept: application/json, application/gzip' \
  --header 'Authorization: Bearer <NYLAS_API_KEY>' \
  --header 'Content-Type: application/json'

{
  "request_id": "1",
  "data": [{
    "birthday": "1960-12-31",
    "company_name": "Nylas",
    "emails": [
      {
        "type": "work",
        "email": "[email protected]"
      },
      {
        "type": "home",
        "email": "[email protected]"
      }
    ],
    "given_name": "Leyah",
    "grant_id": "<NYLAS_GRANT_ID>",
    "groups": [
      {"id": "starred"},
      {"id": "friends"}
    ],
    "id": "<CONTACT_ID>",
    "im_addresses": [
      {
        "type": "jabber",
        "im_address": "jabber_at_leyah"
      },
      {
        "type": "msn",
        "im_address": "leyah.miller"
      }
    ],
    "job_title": "Software Engineer",
    "manager_name": "Nyla",
    "middle_name": "Allison",
    "nickname": "Allie",
    "notes": "Loves ramen",
    "object": "contact",
    "office_location": "123 Main Street",
    "phone_numbers": [
      {
        "type": "work",
        "number": "+1-555-555-5555"
      },
      {
        "type": "home",
        "number": "+1-555-555-5556"
      }
    ],
    "physical_addresses": [
      {
        "type": "work",
        "street_address": "123 Main Street",
        "postal_code": "94107",
        "state": "CA",
        "country": "US",
        "city": "San Francisco"
      },
      {
        "type": "home",
        "street_address": "123 Main Street",
        "postal_code": "94107",
        "state": "CA",
        "country": "US",
        "city": "San Francisco"
      }
    ],
    "picture_url": "https://example.com/picture.jpg",
    "source": "address_book",
    "surname": "Miller",
    "web_pages": [
      {
        "type": "work",
        "url": "<WEBPAGE_URL>"
      },
      {
        "type": "home",
        "url": "<WEBPAGE_URL>"
      }
    ]
  }],
  "next_cursor": "2"
}

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()

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")

contacts = nylas.contacts.list(
  grant_id,
)

print(contacts)

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

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)
  }
}

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");
    }
  }
}

View a contact

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

RequestResponse (JSON)Node.js SDKPython SDKRuby SDKKotlin SDKJava SDK

curl --request GET \
  --url 'https://api.us.nylas.com/v3/grants/<NYLAS_GRANT_ID>/contacts/<CONTACT_ID>' \
  --header 'Accept: application/json, application/gzip' \
  --header 'Authorization: Bearer <NYLAS_API_KEY>' \
  --header 'Content-Type: application/json'

{
  "request_id": "1",
  "data": {
    "birthday": "1960-12-31",
    "company_name": "Nylas",
    "emails": [
      {
      "type": "work",
      "email": "[email protected]"
      },
      {
      "type": "home",
      "email": "[email protected]"
      }
    ],
    "given_name": "Leyah",
    "grant_id": "<NYLAS_GRANT_ID>",
    "groups": [
      {"id": "starred"},
      {"id": "friends"}
    ],
    "id": "<CONTACT_ID>",
    "im_addresses": [
      {
        "type": "jabber",
        "im_address": "leyah_jabber"
      },
      {
        "type": "msn",
        "im_address": "leyah_msn"
      }
    ],
    "job_title": "Software Engineer",
    "manager_name": "Bill",
    "middle_name": "Allison",
    "nickname": "Allie",
    "notes": "Loves ramen",
    "object": "contact",
    "office_location": "123 Main Street",
    "phone_numbers": [
      {
        "type": "work",
        "number": "+1-555-555-5555"
      },
      {
        "type": "home",
        "number": "+1-555-555-5556"
      }
    ],
    "physical_addresses": [
      {
        "type": "work",
        "street_address": "123 Main Street",
        "postal_code": "94107",
        "state": "CA",
        "country": "US",
        "city": "San Francisco"
      },
      {
        "type": "home",
        "street_address": "123 Main Street",
        "postal_code": "94107",
        "state": "CA",
        "country": "US",
        "city": "San Francisco"
      }
    ],
    "picture_url": "https://example.com/picture.jpg",
    "source": "address_book",
    "surname": "Miller",
    "web_pages": [
      {
        "type": "work",
        "url": "<WEBPAGE_URL>"
      },
      {
        "type": "home",
        "url": "<WEBPAGE_URL>"
      }
    ]
  }
}

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

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)
}

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

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.

RequestResponse (JSON)

curl --request GET \
  --url 'https://api.us.nylas.com/v3/grants/<NYLAS_GRANT_ID>/contacts/<CONTACT_ID>?profile_picture=true' \
  --header 'Accept: application/json, application/gzip' \
  --header 'Authorization: Bearer <NYLAS_API_KEY>' \
  --header 'Content-Type: application/json'

{
  "request_id": "1",
  "data": {
    "birthday": "1960-12-31",
    "emails": [{
      "type": "home",
      "email": "[email protected]"
    }],
    "given_name": "Leyah",
    "grant_id": "<NYLAS_GRANT_ID>",
    "groups": [
      {"id": "starred"},
      {"id": "friends"}
    ],
    "id": "<CONTACT_ID>",
    "middle_name": "Allison",
    "nickname": "Allie",
    "object": "contact",
    "phone_numbers": [{
      "type": "home",
      "number": "+1-555-555-5556"
    }],
    "physical_addresses": [{
      "type": "home",
      "street_address": "123 Main Street",
      "postal_code": "94107",
      "state": "CA",
      "country": "US",
      "city": "San Francisco"
    }],
    "picture_url": "https://example.com/picture.jpg",
    "picture": "data:image/jpeg;base64,/9j/4AAQSkZJRgABAQAAAQABAAD/4QAqRXhpZgAASUkqAAgAAAABADEB...",
    "source": "address_book",
    "surname": "Miller"
  }
}

Create a contact

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

RequestResponse (JSON)Node.js SDKPython SDKRuby SDKKotlin SDKJava SDK

curl --request POST \
  --url 'https://api.us.nylas.com/v3/grants/<NYLAS_GRANT_ID>/contacts' \
  --header 'Accept: application/json, application/gzip' \
  --header 'Authorization: Bearer <NYLAS_API_KEY>' \
  --header 'Content-Type: application/json' \
  --data '{
    "birthday": "1960-12-31",
    "company_name": "Nylas",
    "emails": [
      {
        "email": "[email protected]",
        "type": "work"
      },
      {
        "email": "[email protected]",
        "type": "home"
      }
    ],
    "given_name": "Leyah",
    "groups": [
      {
        "id": "starred"
      },
      {
        "id": "friends"
      }
    ],
    "im_addresses": [
      {
        "type": "jabber",
        "im_address": "leyah_jabber"
      },
      {
        "type": "msn",
        "im_address": "leyah_msn"
      }
    ],
    "job_title": "Software Engineer",
    "manager_name": "Bill",
    "middle_name": "Allison",
    "nickname": "Allie",
    "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",
    "surname": "Miller",
    "web_pages": [
      {
        "type": "work",
        "url": "<WEBPAGE_URL>"
      },
      {
        "type": "home",
        "url": "<WEBPAGE_URL>"
      }
    ]
  }'

{
  "request_id": "1",
  "data": {
    "birthday": "1960-12-31",
    "company_name": "Nylas",
    "emails": [
      {
        "type": "work",
        "email": "[email protected]"
      },
      {
        "type": "home",
        "email": "[email protected]"
      }
    ],
    "given_name": "Leyah",
    "grant_id": "<NYLAS_GRANT_ID>",
    "groups": [
      {"id": "starred"},
      {"id": "friends"}
    ],
    "id": "<CONTACT_ID>",
    "im_addresses": [
      {
        "type": "jabber",
        "im_address": "leyah_jabber"
      },
      {
        "type": "msn",
        "im_address": "leyah_msn"
      }
    ],
    "job_title": "Software Engineer",
    "manager_name": "Bill",
    "middle_name": "Allison",
    "nickname": "Allie",
    "notes": "Loves ramen",
    "object": "contact",
    "office_location": "123 Main Street",
    "phone_numbers": [
      {
        "type": "work",
        "number": "+1-555-555-5555"
      },
      {
        "type": "home",
        "number": "+1-555-555-5556"
      }
    ],
    "physical_addresses": [
      {
        "type": "work",
        "street_address": "123 Main Street",
        "postal_code": "94107",
        "state": "CA",
        "country": "US",
        "city": "San Francisco"
      },
      {
        "type": "home",
        "street_address": "321 Pleasant Drive",
        "postal_code": "94107",
        "state": "CA",
        "country": "US",
        "city": "San Francisco"
      }
    ],
    "picture_url": "https://example.com/picture.jpg",
    "source": "address_book",
    "surname": "Miller",
    "web_pages": [
      {
        "type": "work",
        "url": "<WEBPAGE_URL>"
      },
      {
      "type": "home",
      "url": "<WEBPAGE_URL>"
      }
    ]
  }
}

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

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

Modify a contact

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

RequestResponse (JSON)Node.js SDKPython SDKRuby SDKKotlin SDKJava SDK

curl --request PUT \
  --url 'https://api.us.nylas.com/v3/grants/<NYLAS_GRANT_ID>/contacts/<CONTACT_ID>' \
  --header 'Accept: application/json, application/gzip' \
  --header 'Authorization: Bearer <NYLAS_API_KEY>' \
  --header 'Content-Type: application/json' \
  --data '{
    "job_title": "Senior Software Engineer"
  }'

{
  "request_id": "1",
  "data": {
    "birthday": "1960-12-31",
    "company_name": "Nylas",
    "emails": [
      {
        "type": "work",
        "email": "[email protected]"
      },
      {
        "type": "home",
        "email": "[email protected]"
      }
    ],
    "given_name": "Leyah",
    "grant_id": "<NYLAS_GRANT_ID>",
    "groups": [{ "id": "starred" }, { "id": "friends" }],
    "id": "<CONTACT_ID>",
    "im_addresses": [
      {
        "type": "jabber",
        "im_address": "leyah_jabber"
      },
      {
        "type": "msn",
        "im_address": "leyah_msn"
      }
    ],
    "job_title": "Senior Software Engineer",
    "manager_name": "Bill",
    "middle_name": "Allison",
    "nickname": "Allie",
    "notes": "Loves ramen",
    "object": "contact",
    "office_location": "123 Main Street",
    "phone_numbers": [
      {
        "type": "work",
        "number": "+1-555-555-5555"
      },
      {
        "type": "home",
        "number": "+1-555-555-5556"
      }
    ],
    "physical_addresses": [
      {
        "type": "work",
        "street_address": "123 Main Street",
        "postal_code": "94107",
        "state": "CA",
        "country": "US",
        "city": "San Francisco"
      },
      {
        "type": "home",
        "street_address": "321 Pleasant Drive",
        "postal_code": "94107",
        "state": "CA",
        "country": "US",
        "city": "San Francisco"
      }
    ],
    "picture_url": "https://example.com/picture.jpg",
    "source": "address_book",
    "surname": "Miller",
    "web_pages": [
      {
        "type": "work",
        "url": "<WEBPAGE_URL>"
      },
      {
        "type": "home",
        "url": "<WEBPAGE_URL>"
      }
    ]
  }
}

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.*

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)
}

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

Delete a contact

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

RequestNode.js SDKPython SDKRuby SDKKotlin SDKJava SDK

curl --request DELETE \
  --url 'https://api.us.nylas.com/v3/grants/<NYLAS_GRANT_ID>/contacts/<CONTACT_ID>' \
  --header 'Accept: application/json, application/gzip' \
  --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 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)
}

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

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.

RequestResponse (JSON)Node.js SDKPython SDKRuby SDKKotlin SDKJava SDK

curl --request GET \
  --url 'https://api.us.nylas.com/v3/grants/<NYLAS_GRANT_ID>/contacts/groups' \
  --header 'Accept: application/json, application/gzip' \
  --header 'Authorization: Bearer <NYLAS_API_KEY>' \
  --header 'Content-Type: application/json'

{
  "request_id": "1",
  "data": [
    {
      "grant_id": "<NYLAS_GRANT_ID>",
      "group_type": "system",
      "id": "starred",
      "name": "starred",
      "object": "contact_group",
      "path": "parentId/starred"
    },
    {
      "grant_id": "<NYLAS_GRANT_ID>",
      "group_type": "user",
      "id": "friends",
      "name": "friends",
      "object": "contact_group",
      "path": "parentId/friends"
    }
  ],
  "next_cursor": "2"
}

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 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)
}

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

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.