DEV Community

Qasim
Qasim

Posted on

Sync and manage contacts across providers: Nylas Contacts API

#api #devtools #productivity #contacts

Contacts are messier than they look. A user's real address book is spread across the people they've saved by hand, the people they've emailed often enough that the provider auto-collected them, and the colleagues in their company directory. Google exposes these through the People API; Microsoft through Graph; both model the data differently and split it across sources you have to query separately.

The Nylas Contacts API unifies all of that behind one schema and one grant_id. You read saved contacts, auto-collected contacts, and directory contacts through the same endpoint, create and update entries that sync back to the provider, and organize them into groups. This post walks the contact surface from the HTTP API and the Nylas CLI, which mirrors every operation for terminal use.

I work on the CLI, so the terminal commands below are the ones I run when I'm exploring an address book.

The contact model and its three sources

A contact in Nylas carries the fields you'd expect — given_name, surname, emails, phone_numbers, company_name, job_title, notes — plus richer ones like im_addresses, physical_addresses, and web_pages. The schema is the same across providers, so a Google contact and a Microsoft contact deserialize into one struct.

The detail that trips people up is source. Every contact has one of three sources, and they mean very different things:

  • address_book — contacts the user saved deliberately. This is the real address book.
  • inbox — contacts the provider auto-collected because the user emailed them. These were never explicitly saved.
  • domain — contacts from the organization's directory (coworkers).

Knowing the source matters because "all contacts" usually isn't what you want. If you're building a contact picker, the inbox source can flood it with one-off recipients the user doesn't think of as contacts. Filter by source deliberately. See the Contacts API overview for the full data model.

Before you begin

You need a Nylas API key and a connected account with contacts scopes. The CLI gets you set up in two commands:

nylas init        # create an account, generate an API key
nylas auth login  # connect an account over OAuth, store the grant
Enter fullscreen mode Exit fullscreen mode

After login the CLI runs against that grant by default, so the nylas contacts commands below don't need an explicit ID. For the OAuth scopes Google and Microsoft require to read and write contacts, see the authentication docs.

List contacts

Listing is the first thing you'll do. The CLI returns 50 contacts by default and lets you filter by source so you're not drowning in auto-collected addresses:

# 50 contacts, default
nylas contacts list

# Only the real, saved address book
nylas contacts list --source address_book --limit 100
Enter fullscreen mode Exit fullscreen mode

The --limit flag auto-paginates once you raise it above 200. Over HTTP, the same operation is a GET against the contacts collection, with source, email, phone_number, and group as query parameters:

curl --request GET \
  --url "https://api.us.nylas.com/v3/grants/<GRANT_ID>/contacts?source=address_book&limit=100" \
  --header "Authorization: Bearer <NYLAS_API_KEY>"
Enter fullscreen mode Exit fullscreen mode

The list contacts reference documents every filter, and the response paginates with the page_token cursor just like messages and events. The CLI flags live at contacts list.

Create a contact

Creating a contact writes it back to the provider, so it shows up in the user's Google Contacts or Outlook address book too. The CLI uses friendly flag names:

nylas contacts create \
  --first-name "Jane" \
  --last-name "Smith" \
  --email "jane@company.com" \
  --phone "+1-555-123-4567" \
  --company "Acme Corp" \
  --job-title "Engineer"
Enter fullscreen mode Exit fullscreen mode

One thing worth knowing: the CLI flag names are not the API field names. The CLI maps --first-name to given_name, --last-name to surname, --email to the emails array, and --phone to phone_numbers. When you call the API directly, use the API names. Note that emails and phone_numbers are arrays of objects, because a contact can have several of each:

curl --request POST \
  --url "https://api.us.nylas.com/v3/grants/<GRANT_ID>/contacts" \
  --header "Authorization: Bearer <NYLAS_API_KEY>" \
  --header "Content-Type: application/json" \
  --data '{
    "given_name": "Jane",
    "surname": "Smith",
    "company_name": "Acme Corp",
    "job_title": "Engineer",
    "emails": [{ "email": "jane@company.com", "type": "work" }],
    "phone_numbers": [{ "number": "+1-555-123-4567", "type": "work" }]
  }'
Enter fullscreen mode Exit fullscreen mode

The full field list — including birthday, im_addresses, physical_addresses, manager_name, and web_pages — is in the create contact reference, and the CLI flags are at contacts create.

Those array fields come with provider-specific caps that bite if you assume everyone allows many values. IMAP, iCloud, and Yahoo accept at most one email address and one phone number per contact. Microsoft and EWS allow up to three email addresses. Microsoft caps phone numbers at two home, two work, and one mobile. So a contact with four email addresses that round-trips fine on Google will silently lose values on an iCloud account. Field types carry provider rules too: the mobile phone type is Google and Microsoft Graph only, and the other type is Google and EWS only. If you support multiple providers, store the canonical contact in your own system and treat the provider copy as a projection that may drop fields it can't represent.

Search and filter

When you need to find a contact rather than list everything, the CLI's search layers structured filters on top of the list endpoint. You can match by company, email, phone, group, or restrict to contacts that actually have an email address:

# Everyone at one company who has an email on file
nylas contacts search --company "Acme" --has-email

# A specific person by email
nylas contacts search --email "jane@company.com"
Enter fullscreen mode Exit fullscreen mode

The --company filter does a partial match against the company_name field, which is handy when you don't know the exact legal name. The --has-email flag is the one I reach for most — it strips out directory or auto-collected entries that have a name but no usable email, which is exactly the noise you want gone in a contact picker. Full options are at contacts search.

Organize with contact groups

Providers expose contact groups (Google calls them labels; Outlook calls them categories) and Nylas reads them through a dedicated endpoint. Listing groups gives you the IDs you then use to filter contacts:

nylas contacts groups list
Enter fullscreen mode Exit fullscreen mode

Over HTTP that's a GET to the contact-groups collection:

curl --request GET \
  --url "https://api.us.nylas.com/v3/grants/<GRANT_ID>/contacts/groups" \
  --header "Authorization: Bearer <NYLAS_API_KEY>"
Enter fullscreen mode Exit fullscreen mode

Once you have a group ID, pass it as the group filter on a contacts list or search call to get just that group's members. The list contact groups reference and the contacts groups list command cover the rest. Groups are read-mapped from the provider, so the IDs are stable references you can store.

Profile photos and sync

Contacts often have a profile photo, which Nylas serves separately from the contact record so you only fetch image bytes when you need them. The CLI downloads a contact's photo to a file:

nylas contacts photo download <contact-id> --output ./jane.jpg
Enter fullscreen mode Exit fullscreen mode

The contacts photo download command handles the fetch. There's also a nylas contacts sync command that reports sync status for the account's contacts, which is useful when you've just connected a grant and want to know whether the initial contact sync has finished before you rely on the data being complete.

Limits and provider notes

Dimension Value Notes
Default page size 50 contacts --limit auto-paginates above 200
Sources address_book, inbox, domain Filter deliberately — inbox is auto-collected
Providers Google, Microsoft, and more One contact schema across all
Multi-value fields emails, phone_numbers are arrays A contact can hold several of each
Groups Read-mapped from the provider Google labels / Outlook categories

The biggest practical gotcha is the inbox source. A user who emails a lot can accumulate thousands of auto-collected inbox contacts they never deliberately saved, so a naive "show me all contacts" pulls in a long tail of one-off recipients. Decide up front which sources your feature should surface.

Wrapping up

Contacts are deceptively simple — until you account for the three sources, the multi-value fields, and the fact that two providers model the same address book differently. Reading and writing them through one schema, with the source distinction made explicit, turns a fiddly multi-API integration into a handful of calls. The CLI gives you the same operations in the terminal, so you can inspect an address book and test a write before you build the feature around it.

Where to go next:

Written by Qasim Muhammad and Pouya Sanooei.

Top comments (0)