Skip to content
Skip to main content

Nylas Contacts API guide

Last updated:

Building a contact picker or an address-book sync usually means wiring up two separate integrations: Google’s People API with people.connections.list and its own OAuth scopes, and Microsoft Graph with GET /me/contacts and a different permission model. The field names don’t line up, the paging differs, and neither one reads the other’s data. The Nylas Contacts API collapses both into a single endpoint with one schema, so the code you write for a Gmail address book also reads an Outlook one without a provider branch.

This page maps out what you can build, which providers are covered, where Google and Microsoft diverge, and links to a recipe for every contact task.

What the Contacts API does

Section titled “What the Contacts API does”

The Contacts API gives you a single REST interface over a user’s address book across every provider Nylas connects, returning one contact object whether the account is Google, Microsoft, iCloud, Yahoo, IMAP, or Exchange. Each contact carries the same fields (emails, phone_numbers, job_title, company_name, groups, and more), so one parser handles every account type you connect.

The core operations cover the full lifecycle of a contact:

  • List contacts with GET /v3/grants/{grant_id}/contacts, filtered by email, source, or group.
  • Get a single contact with GET /v3/grants/{grant_id}/contacts/{contact_id}.
  • Create a contact with POST /v3/grants/{grant_id}/contacts.
  • Update a contact with PUT /v3/grants/{grant_id}/contacts/{contact_id}.
  • Delete a contact with DELETE /v3/grants/{grant_id}/contacts/{contact_id}.
  • List groups with GET /v3/grants/{grant_id}/contacts/groups to surface a user’s Gmail groups or Outlook categories.

That’s 6 endpoints total. For the full field reference, see Manage contacts with the Contacts API.

Supported contact providers

Section titled “Supported contact providers”

The Contacts API spans the same providers Nylas connects for email: Google, Microsoft, iCloud, Yahoo, IMAP, and Exchange (EWS). Each one stores contacts behind a different native protocol with its own auth model, and the API normalizes all of them into one contact object and one set of endpoints so your integration doesn’t change when a user signs in with a different account.

The table maps each provider to what sits underneath the unified call.

ProviderUnderlying APIAuthNotes
GooglePeople APIOAuth 2.0 scopesReturned through the unified Nylas contact schema
MicrosoftMicrosoft GraphOAuth 2.0 scopesReturned through the same unified contact schema
Exchange (EWS)EWS contactsBasic or OAuthSame schema, with a few field and group limits
iCloud, Yahoo, IMAPCardDAV / IMAPApp password or OAuthSame schema; some filters are provider-specific

Filter support varies by provider: the group filter isn’t available on Exchange (EWS), recurse is Microsoft-only, and phone_number filtering covers Google, IMAP, iCloud, Yahoo, and EWS. The unified schema is the same everywhere, but Google and Microsoft offer the richest group and profile-photo support, so lean on them when those features matter.

How contacts differ between Google and Microsoft

Section titled “How contacts differ between Google and Microsoft”

The two providers organize contacts in genuinely different ways, and a few of those differences leak through the unified schema. Google groups contacts with labels and auto-collects everyone you’ve emailed into an “other contacts” pool, while Microsoft uses contact folders plus categories. Across both, Nylas reads from 3 contact sources: address_book, domain, and inbox.

Here are the concrete differences worth planning for:

  • Grouping model. Google exposes user-created contact groups and system groups like “starred”. Microsoft uses categories on contacts and organizes them into contact folders. Both surface through the same groups endpoint.
  • Auto-collected contacts. Google’s “other contacts” pool holds people you’ve emailed but never saved. Reaching it needs the contacts.other.readonly scope and maps to the inbox source. Microsoft surfaces correspondents through People.Read.
  • Email address limits. Microsoft Graph caps a contact at 3 email addresses and leaves the email type as null, so don’t rely on work or home labels for Outlook contacts. Google doesn’t impose the same cap.
  • Writable sources. Both providers let you create and update saved contacts. The auto-collected and directory sources are read-only on both.
  • Sync timing. Google has no push API for contacts, so Nylas polls every 5 minutes. Microsoft delivers changes faster.

For the provider-specific walkthroughs, see List Google contacts and List Microsoft contacts.

Contacts recipes

Section titled “Contacts recipes”

Each recipe below covers one contact task end to end. Together they span all 7 of the section’s how-to guides, from reading an address book to keeping it in sync.

  • List Google contacts reads a Gmail or Google Workspace address book and covers People API scopes, groups, and the “other contacts” pool.
  • List Microsoft contacts reads an Outlook or Microsoft 365 address book and covers Graph permissions, contact folders, and categories.
  • Create and update contacts writes new contacts and edits existing ones with the unified schema across providers.
  • Search contacts narrows an address book by email, name, or group so you return only the contacts a query needs.
  • Recipient autocomplete powers a contact picker from the inbox source so suggestions include real correspondents, not just saved contacts.
  • Contact groups lists a user’s Gmail groups or Outlook categories and scopes a contact query to one group.
  • List and sync contacts fetches contacts from Google and Outlook in one call and keeps them current with contact.updated and contact.deleted webhooks.

What’s next

Section titled “What’s next”