Quickstart: Contacts API

The Nylas Contacts API gives you access to a user’s address book across Google, Microsoft, EWS, hosted IMAP, native iCloud, and native Yahoo grants through one API. Native iCloud and Yahoo grants use CardDAV for the default address_book source; generic hosted IMAP grants keep their existing Contact behavior.

This quickstart walks you through listing, searching, and creating contacts on behalf of a connected user.

Before you begin

You need two things from Nylas to make API calls:

1. An API key — authenticates your application. You’ll pass it as a Bearer token.
2. A grant ID — identifies which user’s contacts to access. You get one when you connect an account to Nylas.

If you don’t have these yet, follow one of the setup guides first:

• Get started with the CLI — run nylas init to create an account, generate an API key, and connect a test account in one command.
• Get started with the Dashboard — do the same steps through the web UI.

Then install the Nylas SDK for your language:

Node.jsPythonRuby

npm install nylas

pip install nylas

gem install nylas

For Java and Kotlin, see the Kotlin/Java SDK setup guide.

List a user’s contacts

Retrieve contacts from a user’s address book. Replace <NYLAS_GRANT_ID> and <NYLAS_API_KEY> with your values.

curlNode.jsPythonRubyJavaKotlinCLI

curl --request GET \
  --url 'https://api.us.nylas.com/v3/grants/<NYLAS_GRANT_ID>/contacts?limit=10' \
  --header 'Authorization: Bearer <NYLAS_API_KEY>'

import Nylas from "nylas";

const nylas = new Nylas({ apiKey: process.env.NYLAS_API_KEY });

const contacts = await nylas.contacts.list({
  identifier: process.env.NYLAS_GRANT_ID,
  queryParams: { limit: 10 },
});

contacts.data.forEach((contact) => {
  console.log(`${contact.givenName} ${contact.surname} -- ${contact.emails?.[0]?.email}`);
});

import os
from nylas import Client

nylas = Client(os.environ["NYLAS_API_KEY"])

contacts = nylas.contacts.list(
    os.environ["NYLAS_GRANT_ID"],
    query_params={"limit": 10},
)

for contact in contacts.data:
    email = contact.emails[0].email if contact.emails else "no email"
    print(f"{contact.given_name} {contact.surname} -- {email}")

require 'nylas'

nylas = Nylas::Client.new(api_key: ENV['NYLAS_API_KEY'])

contacts, _ = nylas.contacts.list(
  identifier: ENV['NYLAS_GRANT_ID'],
  query_params: { limit: 10 }
)

contacts.each do |contact|
  email = contact[:emails]&.first&.dig(:email) || 'no email'
  puts "#{contact[:given_name]} #{contact[:surname]} -- #{email}"
end

import com.nylas.NylasClient;
import com.nylas.models.*;

public class ListContacts {
  public static void main(String[] args) throws NylasSdkTimeoutError, NylasApiError {
    NylasClient nylas = new NylasClient.Builder("<NYLAS_API_KEY>").build();

    ListContactsQueryParams queryParams = new ListContactsQueryParams.Builder().limit(10).build();
    ListResponse<Contact> contacts = nylas.contacts().list("<NYLAS_GRANT_ID>", queryParams);

    for (Contact contact : contacts.getData()) {
      System.out.println(contact.getGivenName() + " " + contact.getSurname());
    }
  }
}

import com.nylas.NylasClient
import com.nylas.models.*

fun main() {
    val nylas = NylasClient(apiKey = "<NYLAS_API_KEY>")

    val queryParams = ListContactsQueryParams(limit = 10)
    val contacts = nylas.contacts().list("<NYLAS_GRANT_ID>", queryParams).data

    for (contact in contacts) {
        println("${contact.givenName} ${contact.surname}")
    }
}

nylas contacts list --limit 10

Search for a contact

Find contacts by email address. Useful for looking up a sender’s details before replying, or checking if a contact exists before creating one.

curlNode.jsPythonRubyJavaKotlinCLI

curl --request GET \
  --url 'https://api.us.nylas.com/v3/grants/<NYLAS_GRANT_ID>/[email protected]' \
  --header 'Authorization: Bearer <NYLAS_API_KEY>'

const results = await nylas.contacts.list({
  identifier: process.env.NYLAS_GRANT_ID,
  queryParams: { email: "[email protected]" },
});

console.log(`Found ${results.data.length} contacts`);

results = nylas.contacts.list(
    os.environ["NYLAS_GRANT_ID"],
    query_params={"email": "[email protected]"},
)

print(f"Found {len(results.data)} contacts")

results, _ = nylas.contacts.list(
  identifier: ENV['NYLAS_GRANT_ID'],
  query_params: { email: '[email protected]' }
)

puts "Found #{results.length} contacts"

ListContactsQueryParams searchParams = new ListContactsQueryParams.Builder()
    .email("[email protected]")
    .build();

ListResponse<Contact> results = nylas.contacts().list("<NYLAS_GRANT_ID>", searchParams);
System.out.println("Found " + results.getData().size() + " contacts");

val searchParams = ListContactsQueryParams(email = "[email protected]")
val results = nylas.contacts().list("<NYLAS_GRANT_ID>", searchParams).data

println("Found ${results.size} contacts")

nylas contacts search --email [email protected]

Create a contact

Add a new contact to a user’s address book.

curlNode.jsPythonRubyJavaKotlinCLI

curl --request POST \
  --url 'https://api.us.nylas.com/v3/grants/<NYLAS_GRANT_ID>/contacts' \
  --header 'Authorization: Bearer <NYLAS_API_KEY>' \
  --header 'Content-Type: application/json' \
  --data '{
    "given_name": "Alice",
    "surname": "Smith",
    "company_name": "Acme Corp",
    "job_title": "Engineering Manager",
    "emails": [{ "email": "[email protected]", "type": "work" }],
    "phone_numbers": [{ "number": "+1-555-555-1234", "type": "work" }]
  }'

const contact = await nylas.contacts.create({
  identifier: process.env.NYLAS_GRANT_ID,
  requestBody: {
    givenName: "Alice",
    surname: "Smith",
    companyName: "Acme Corp",
    jobTitle: "Engineering Manager",
    emails: [{ email: "[email protected]", type: "work" }],
    phoneNumbers: [{ number: "+1-555-555-1234", type: "work" }],
  },
});

console.log("Created contact:", contact.data.id);

contact = nylas.contacts.create(
    os.environ["NYLAS_GRANT_ID"],
    request_body={
        "given_name": "Alice",
        "surname": "Smith",
        "company_name": "Acme Corp",
        "job_title": "Engineering Manager",
        "emails": [{"email": "[email protected]", "type": "work"}],
        "phone_numbers": [{"number": "+1-555-555-1234", "type": "work"}],
    },
)

print("Created contact:", contact.data.id)

contact, _ = nylas.contacts.create(
  identifier: ENV['NYLAS_GRANT_ID'],
  request_body: {
    given_name: 'Alice',
    surname: 'Smith',
    company_name: 'Acme Corp',
    job_title: 'Engineering Manager',
    emails: [{ email: '[email protected]', type: 'work' }],
    phone_numbers: [{ number: '+1-555-555-1234', type: 'work' }]
  }
)

puts "Created contact: #{contact[:id]}"

import com.nylas.NylasClient;
import com.nylas.models.*;
import java.util.List;

public class CreateContact {
  public static void main(String[] args) throws NylasSdkTimeoutError, NylasApiError {
    NylasClient nylas = new NylasClient.Builder("<NYLAS_API_KEY>").build();

    CreateContactRequest requestBody = new CreateContactRequest.Builder()
        .givenName("Alice")
        .surname("Smith")
        .companyName("Acme Corp")
        .jobTitle("Engineering Manager")
        .emails(List.of(new ContactEmail("[email protected]", "work")))
        .phoneNumbers(List.of(new ContactPhoneNumber("+1-555-555-1234", "work")))
        .build();

    Response<Contact> contact = nylas.contacts().create("<NYLAS_GRANT_ID>", requestBody);
    System.out.println("Created contact: " + contact.getData().getId());
  }
}

import com.nylas.NylasClient
import com.nylas.models.*

fun main() {
    val nylas = NylasClient(apiKey = "<NYLAS_API_KEY>")

    val requestBody = CreateContactRequest(
        givenName = "Alice",
        surname = "Smith",
        companyName = "Acme Corp",
        jobTitle = "Engineering Manager",
        emails = listOf(ContactEmail("[email protected]", "work")),
        phoneNumbers = listOf(ContactPhoneNumber("+1-555-555-1234", "work"))
    )

    val contact = nylas.contacts().create("<NYLAS_GRANT_ID>", requestBody)
    println("Created contact: ${contact.data.id}")
}

nylas contacts create \
  --first-name "Alice" \
  --last-name "Smith" \
  --email [email protected] \
  --phone "+1-555-555-1234" \
  --company "Acme Corp" \
  --job-title "Engineering Manager"

What’s next

• Authentication — set up OAuth so your users can connect their accounts
• Email API quickstart — send and read email
• Webhooks — get notified when contacts are created or updated
• Contacts API reference — full endpoint documentation