Sync Contacts Across Gmail and Outlook

How does contact sync work across Gmail and Outlook?

Contact access in Nylas v3 is passthrough, not a stored sync: each request is forwarded straight to Google or Microsoft and the response comes back with provider-native IDs, so the data is always current and there's no initial-sync wait. The CLI's nylas contacts sync command documents this model directly.

The practical upshot: there is no “sync state” for you to store or monitor. You read live contacts on demand and, if you want a local copy for speed, you own that cache. Because IDs are provider-native, a contact from Gmail and the same person from Outlook carry two different IDs — which is exactly why you dedupe on email, not on ID.

How do I list contacts from both providers?

You list each account by switching the active grant and reading contacts as JSON. The nylas auth list command shows your connected accounts; nylas auth switch changes which one subsequent commands target. Pull both into separate files so the next step can merge them.

# Pull Google contacts, then Microsoft contacts, into two files
nylas auth switch work@gmail.com
nylas contacts list --json > google-contacts.json

nylas auth switch work@outlook.com
nylas contacts list --json > outlook-contacts.json

Each record carries the contact's name and one or more email addresses. The shape is identical across providers because the CLI normalizes them, so your merge logic doesn't branch on which backend a contact came from.

How do I deduplicate contacts across providers?

You deduplicate by keying on the lowercased primary email address, since that's the one stable identifier both providers share. Concatenate the two lists, group by email, and keep the first occurrence — or prefer the record with more fields filled in. The jq below produces a single merged list with one entry per unique address.

# Merge both lists, one entry per lowercased email address
jq -s 'add
  | map({ key: (.emails[0].email // "" | ascii_downcase), value: . })
  | group_by(.key)
  | map(.[0].value)' \
  google-contacts.json outlook-contacts.json > merged-contacts.json

jq 'length' merged-contacts.json

How do I get notified when a contact changes?

You subscribe to contact events with a webhook, but the freshness depends on the provider. Per the contacts sync documentation, Microsoft delivers real-time updates via Graph, while Google contact changes are polled approximately every 5 minutes because of a Google API limitation. Build for the slower path: assume up to a 5-minute lag on Google-side changes.

# Notify your endpoint when a contact is created or updated
nylas webhook create \
  --url https://your-server.example.com/contact-events \
  --triggers contact.created,contact.updated \
  --description "contact change feed"

Because the two providers converge at different speeds, don't treat a missing Google notification as “no change” for several minutes. For anything that must be exact — a billing email, say — re-read the contact on demand rather than trusting the last webhook you received.

How do I keep a unified contact cache?

You keep a fast local cache by storing the merged list keyed on email and refreshing it on a schedule plus on webhook events. The official guidance is explicit: don't store Nylas-specific sync state, do cache locally if you need fast repeated access, and handle provider rate limits gracefully. A 5-minute refresh aligns neatly with Google's polling cadence.

Write the cache so a re-run is idempotent: upsert by email, never append blindly, so a contact that appears in both providers stays one row. Pair this with enriching contacts from email when you want to fill gaps the address books don't have.

Next steps

• Manage contacts from the terminal — create, update, search, and delete contacts
• Enrich contacts from email — fill in missing fields from message history
• Map organization contacts — build a company graph from your address books
• Contacts API comparison — how Google People and Microsoft Graph contacts differ
• Command reference — every flag, subcommand, and example
• Google People API — the Google side of contact reads and the 5-minute poll
• Microsoft Graph: contact resource — the Outlook side, with real-time change notifications
• RFC 6350 — vCard — the interchange format if you export the merged list