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.
