Build recipient autocomplete

Type two letters into Gmail’s “To:” field and it suggests the right person before you finish their name. Users now expect that everywhere, and a blank compose box with no suggestions feels broken. Building it per provider is the painful part: Google’s People API and Microsoft Graph each have their own auth, paging, and field names, and neither one covers the other’s contacts.

The Nylas Contacts API returns supported provider address books through one endpoint with one schema. You pull contacts once, cache them, and filter on the client as the user types. The same pattern works for Google, Microsoft, Exchange, hosted IMAP, native iCloud, and native Yahoo grants.

How do I build recipient autocomplete from contacts?

Recipient autocomplete is a 3-step pattern: fetch the user’s contacts once, cache them in memory, then filter that cache by prefix on every keystroke. You hit the API a handful of times at load, not once per character, so suggestions render in under a millisecond instead of waiting on a network round trip for each letter typed.

The steps below map directly to the sections in this recipe:

Fetch all contacts from the Contacts API and page through the results.
Cache them in a flat list of { name, email } entries keyed for fast prefix matching.
Filter that cache as the user types, delaying input processing so you rank and render only the top few matches.

The same flow covers supported providers because the API returns one unified Contact object. You write the picker once instead of branching on the provider.

Fetch contacts to build the index

Send a GET request to /v3/grants/{grant_id}/contacts to read the user’s address book. The response is a data array of contact objects, each carrying an emails array plus name fields like given_name and surname. The default page size is 30 contacts and the maximum is 200, so you typically page through everyone once at load and cache the result.

The request below lists contacts for a grant. Raise limit to 200 to cut the number of round trips, then follow the next_cursor to fetch the next page.

curl --compressed --request GET \
  --url 'https://api.us.nylas.com/v3/grants/<NYLAS_GRANT_ID>/contacts' \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer <NYLAS_API_KEY>' \
  --header 'Content-Type: application/json'

{
  "request_id": "1",
  "data": [
    {
      "birthday": "1960-12-31",
      "company_name": "Nylas",
      "emails": [
        {
          "type": "work",
          "email": "[email protected]"
        },
        {
          "type": "home",
          "email": "[email protected]"
        }
      ],
      "given_name": "Leyah",
      "grant_id": "<NYLAS_GRANT_ID>",
      "groups": [{ "id": "starred" }, { "id": "friends" }],
      "id": "<CONTACT_ID>",
      "im_addresses": [
        {
          "type": "jabber",
          "im_address": "jabber_at_leyah"
        },
        {
          "type": "msn",
          "im_address": "leyah.miller"
        }
      ],
      "job_title": "Software Engineer",
      "manager_name": "Nyla",
      "middle_name": "Allison",
      "metadata": {
        "key1": "customer-123",
        "crm_record": "crm-456"
      },
      "nickname": "Allie",
      "notes": "Loves ramen",
      "object": "contact",
      "office_location": "123 Main Street",
      "phone_numbers": [
        {
          "type": "work",
          "number": "+1-555-555-5555"
        },
        {
          "type": "home",
          "number": "+1-555-555-5556"
        }
      ],
      "physical_addresses": [
        {
          "type": "work",
          "street_address": "123 Main Street",
          "postal_code": "94107",
          "state": "CA",
          "country": "US",
          "city": "San Francisco"
        },
        {
          "type": "home",
          "street_address": "123 Main Street",
          "postal_code": "94107",
          "state": "CA",
          "country": "US",
          "city": "San Francisco"
        }
      ],
      "picture_url": "https://example.com/picture.jpg",
      "source": "address_book",
      "surname": "Miller",
      "web_pages": [
        {
          "type": "work",
          "url": "<WEBPAGE_URL>"
        },
        {
          "type": "home",
          "url": "<WEBPAGE_URL>"
        }
      ]
    }
  ],
  "next_cursor": "2"
}

import Nylas from "nylas";

const nylas = new Nylas({
  apiKey: "<NYLAS_API_KEY>",
  apiUri: "<NYLAS_API_URI>",
});

async function fetchContacts() {
  try {
    const identifier = "<NYLAS_GRANT_ID>";
    const contacts = await nylas.contacts.list({
      identifier,
      queryParams: {},
    });

    console.log("Recent Contacts:", contacts);
  } catch (error) {
    console.error("Error fetching drafts:", error);
  }
}

fetchContacts();

Pass the next_cursor value as the page_token query parameter to read the next page. Keep looping until a response comes back without a next_cursor, which means you’ve reached the end of the address book.

Build autocomplete from the terminal

The Nylas CLI pulls the contacts that power a recipient autocomplete: nylas contacts search filters by company, email, or phone, and --json output drops straight into an index or cache you build against, so you can prototype the picker from the terminal before writing any code.

# Search contacts to seed an autocomplete index
nylas contacts search --company "Acme" --has-email --json

# Include frequently emailed people, not just saved contacts
nylas contacts list --source inbox --json

Pull both the address_book and inbox sources to cover saved contacts and people the user sends email to often. Each query returns 50 contacts by default. See the contacts search and contacts list command reference.

How do I cache contacts for fast autocomplete?

Cache contacts client-side because per-keystroke API calls are too slow and too expensive. A network round trip adds 50 to 300 milliseconds per request, and a fast typist fires 5 or more keystrokes per second, so live calls both feel slow and burn through rate limits. Filtering an in-memory list instead returns matches in well under a millisecond.

Flatten the API response into one entry per email address, then filter that array by prefix. Wait about 150 milliseconds before processing the input so you match on a pause, not on every letter. The snippet below builds the index once and exposes a search function the input handler calls.

// Flatten contacts into one { name, email } entry per address.
const buildIndex = (contacts) =>
  contacts.flatMap((c) => {
    const name = [c.given_name, c.surname].filter(Boolean).join(" ");
    return (c.emails ?? []).map((e) => ({
      name,
      email: e.email.toLowerCase(),
    }));
  });

// Prefix-match on name or email. Cap results so the dropdown stays short.
const search = (index, query, max = 5) => {
  const q = query.trim().toLowerCase();
  if (!q) return [];
  return index
    .filter((e) => e.name.toLowerCase().startsWith(q) || e.email.startsWith(q))
    .slice(0, max);
};

// Refresh the cache every 5 minutes so new contacts show up.
const index = buildIndex(await fetchAllContacts(grantId));
setInterval(async () => {
  index.length = 0;
  index.push(...buildIndex(await fetchAllContacts(grantId)));
}, 5 * 60 * 1000);

Choose a refresh interval that fits your product and provider limits. For grants that emit Contact notifications, the contact.updated and contact.deleted triggers can patch the cache between reconciliations. Native Yahoo grants don’t emit Contact notifications, so refresh them with paginated list requests. Native iCloud notifications are polled and best effort, so keep periodic reconciliation even when you subscribe.

How do I include people the user writes to but hasn’t saved?

Set the source query parameter to inbox to surface everyone the user has corresponded with, beyond saved contacts. The API recognizes 3 sources: address_book (contacts the user saved), domain (the organization directory), and inbox (contacts generated automatically from sent and received mail). The inbox source is what fills a picker with real correspondents who were never added by hand.

The request below gets inbox contacts for a separate merge with the saved address_book results. Query each source individually unless the specific grant type documents compound source support. Native iCloud and Yahoo grants reject compound source filters; their inbox source is also available only when separately enabled.

Coverage of these automatically generated contacts varies by provider. The inbox source needs the contacts.other.readonly scope on Google and People.Read on Microsoft, and Exchange (EWS) doesn’t support it. Native iCloud and Yahoo inbox contacts are separately gated and read-only. For unsupported grants, build the picker on saved contacts plus recipients you pull from the Messages API. The scopes reference lists the exact strings.

Things to know about autocomplete data

A good recipient picker is more than a prefix filter. A few details separate a usable index from a frustrating one, and most of them come down to how you shape the cached data before it ever reaches the dropdown.

Deduplicate by email, not by name. One person often appears more than once, as a saved address_book entry and again as an automatically generated inbox contact. Lowercase every address and key your index by email address so the same person shows up once. Two contacts can share a display name, so never deduplicate on name alone.

Rank by how often the user writes to someone. Alphabetical order buries the people the user writes to most. Pull recent sent messages from the Messages API, count how often each address appears as a recipient, and sort matches by that frequency. The 5 to 10 most-contacted addresses cover the majority of real sends, so weighting by send count makes the first suggestion correct far more often.

Don’t expose the whole address book. Return suggestions only after the user types at least 2 characters, and cap the dropdown at 5 to 8 entries. Dumping every contact into the page leaks the user’s full network into client-side state and slows rendering. Filter server-side if your address books run to thousands of entries.

Watch the provider quirks. Google organizes contacts into groups and polls for changes every five minutes. Microsoft Graph caps a single contact at three email addresses and can leave the email type as null. Native Yahoo allows at most one email address. Build your ranking on send frequency instead of provider labels.

What’s next

List and sync contacts from Google and Outlook to keep the cache current with webhooks
List Google contacts for Google-specific source and scope details
Using the Contacts API for the full contact schema, filters, and per-provider limits
Email API to pull sent-message recipients and rank suggestions by frequency