A user’s contacts are rarely a flat list. They’ve sorted people into groups: a “Team” group in Gmail, categories in Outlook, a “Clients” label. If your app shows or syncs contacts, respecting those groups makes the experience feel native instead of dumping every contact into one bucket.
The Nylas Contacts API exposes those groups and lets you scope a contact query to one of them, so you can build a group picker or sync a single segment without pulling the whole address book.
How do I list a user’s contact groups?
Section titled “How do I list a user’s contact groups?”Send a GET /v3/grants/{grant_id}/contacts/groups request. Nylas returns each group with an id and a name, mapping the contact groups and categories from 2 providers (Gmail and Outlook) into one shape. You use the group id to filter contacts, so this call is the first step before scoping a query. It returns the same structure regardless of provider.
The request below lists the contact groups on an account.
curl --compressed --request GET \ --url 'https://api.us.nylas.com/v3/grants/<NYLAS_GRANT_ID>/contacts/groups' \ --header 'Accept: application/json' \ --header 'Authorization: Bearer <NYLAS_API_KEY>' \ --header 'Content-Type: application/json'How do I filter contacts by group?
Section titled “How do I filter contacts by group?”Add the group query parameter to a GET /v3/grants/{grant_id}/contacts request, set to the group id from the groups call. Nylas returns only the contacts in that group, which is how you sync or display one segment at a time. The group parameter is supported on 5 of the 6 providers, every one except Exchange (EWS).
The request below returns only the contacts in one group.
curl --request GET \ --url 'https://api.us.nylas.com/v3/grants/<NYLAS_GRANT_ID>/contacts?group=<GROUP_ID>' \ --header 'Authorization: Bearer <NYLAS_API_KEY>'Things to know about contact groups
Section titled “Things to know about contact groups”Provider differences shape what you get back. Gmail exposes user-created contact groups and system groups like “starred”, while Outlook uses categories, and Nylas surfaces both through the same groups endpoint. Group filtering works on 5 of the 6 providers and is unavailable only on Exchange (EWS), so build a fallback for EWS accounts rather than assuming the group parameter always applies.
The groups endpoint is read-only here: you list groups and filter by them, but you manage group membership through each contact’s own groups field. See the Contacts API for membership details.
What’s next
Section titled “What’s next”- List and sync contacts from Google and Outlook for the base contact list and filters
- The Contacts API for group membership and the full contact schema
- Contacts API scopes for the scopes group access needs
- Get real-time updates with webhooks for contact.updated notifications