NYnylas
Contacts

Return all contacts

Changed on

Return contacts from a user's selected source. See Contact sources for provider-specific behavior.

Results include Nylas-managed Contact metadata. When metadata_pair is present, you can't also use email, phone_number, group, recurse, or a non-default source. You can use limit and page_token with metadata_pair. If a metadata record points to a contact that no longer exists at the provider, Nylas removes the stale record while resolving the query.

get/v3/grants/{grant_id}/contacts

Request

  • Base URL
    https://api.us.nylas.com
  • Auth
    • HTTP bearer
    • or HTTP bearer

Query parameters

limitinteger

The maximum number of objects to return. See Pagination for more information.

page_tokenstring

An identifier that specifies which page of data to return. You can get this value from the next_cursor response field. See Pagination for more information.

metadata_pairstring

Pass one indexed metadata key/value pair (for example, ?metadata_pair=key1:value) to search for objects. The key must be key1, key2, key3, key4, or key5. See Metadata for more information.

selectstring

Specify fields that you want Nylas to return, as a comma-separated list (for example, select=id,updated_at). This allows you to receive only the portion of object data that you're interested in. You can use select to optimize response size and reduce latency by limiting queries to only the information that you need.

emailstring

Returns the contacts containing the specified email address.

phone_numberstring

(Google, IMAP, iCloud, Yahoo, and EWS only) Returns contacts containing the specified phone number.

source'address_book' | 'domain' | 'inbox'

Returns contacts from the user's address book, domain, or contacts generated automatically from message participants. To filter for multiple sources, pass a comma-separated list (for example, source=address_book,inbox). See Contact sources for provider availability and behavior.

groupstring

(Not supported for EWS) Returns the contacts included in the specified Contact Group.

recursestring

(Microsoft Only) When true, returns the contacts in the specified Contact Group subgroups. The recursion goes only one level deep.

Response

Contacts

request_idstring

The request ID.

next_cursorstring nullable

A cursor pointing to the next page of results for the request.

Example response

{
  "request_id": "5fa64c92-e840-4357-86b9-2aa364d35b88",
  "next_cursor": "CigKGjRlaDdyNGQydTFqbWJ0bGo5a2QxdWJtdDZnGAEggIDAu7fw7bEYGg8IABIAGPjh2PGEi_0CIAEiBwgCEOqs6i4="
}

Changes

  • a669a04b02baRevision changes
    • breaking

      the //// response's property type changed from object to array for status

  • 763d6b969cd7Revision changes
    • info

      added the optional property / to the response with the status