How to list Yahoo contacts

Yahoo doesn’t ship a public contacts REST API the way Google and Microsoft do. Reading a Yahoo address book means connecting over IMAP, and Yahoo gates that access behind a commercial agreement: you submit a Mail API Access form, sign Yahoo’s Commercial Access Agreement, then run an OAuth flow whose access tokens expire after 3,600 seconds. Most teams don’t want to own that pipeline just to populate a contact picker.

This recipe reads a Yahoo address book through one call to the Nylas Contacts API. You get the same contact schema as a Gmail or Outlook account, so your picker code stays provider-agnostic, and the API handles the IMAP connection and token refresh once a grant exists.

Why use Nylas instead of Yahoo IMAP directly?

Yahoo has no dedicated contacts endpoint, so the native path is IMAP plus an OAuth approval process. Nylas turns that into a single GET request against the unified contact schema. The 4 hurdles below are what you skip:

• Commercial access approval. Yahoo requires a signed Mail Products Commercial Access Agreement before OAuth access to IMAP is granted, and approval isn’t instant.
• Short-lived OAuth tokens. Yahoo access tokens last 3,600 seconds, so you’d refresh constantly. Nylas refreshes the token automatically once the grant is created.
• App-password fallback. Accounts without OAuth fall back to an IMAP app password on imap.mail.yahoo.com port 993. The API accepts both auth paths through one grant model.
• One schema across providers. The same GET /v3/grants/{grant_id}/contacts request reads Yahoo, Gmail, Outlook, iCloud, and Exchange, so your code reads one contact object regardless of provider.

Before you begin

You need a connected Yahoo account and a working project before any contacts come back. A grant represents one authenticated Yahoo mailbox, and the contacts you list always belong to that single grant. Yahoo supports two auth paths: OAuth and app passwords, and you pick one when you create the grant.

• A Nylas application with a valid API key
• A grant for a Yahoo account, connected over OAuth or an app password
• Yahoo commercial access approval, or an app password from the account holder

New to Nylas? Start with the quickstart guide to set up your app and connect a test account before continuing here.

Yahoo OAuth and app-password auth

Yahoo connections take one of two paths. OAuth is the recommended route: you register a confidential client in the Yahoo Apps dashboard, request the mail-r or mail-w scope, and complete a Bring Your Own Authentication handshake. Registering a redirect URI can take up to 24 hours to propagate. If OAuth isn’t an option, the account holder generates an app password and you connect over Hosted IMAP instead. Both paths produce a grant you can list contacts from. The full setup lives in the Yahoo authentication guide.

List Yahoo contacts

Send a GET request to /v3/grants/{grant_id}/contacts with the grant ID for the connected Yahoo account. The response is a data array of contact objects plus a request_id, and by default a single page returns up to 30 contacts (raise it to 200 with the limit parameter). Every object carries the same fields, including emails, phone_numbers, job_title, company_name, and groups, so one parser reads all 3 providers (Yahoo, Gmail, and Outlook) without provider-specific branches.

The samples below list contacts for one grant and print the unified response.

RequestResponseNode.js SDKPython SDK

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",
      "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();

from nylas import Client

nylas = Client(
    "<NYLAS_API_KEY>",
    "<NYLAS_API_URI>"
)

grant_id = "<NYLAS_GRANT_ID>"

contacts = nylas.contacts.list(
  grant_id,
)

print(contacts)

For create, update, and delete operations plus the complete field list, see Manage contacts with the Contacts API.

List Yahoo contacts from the terminal

Yahoo serves contacts over IMAP, so a grant authenticates with OAuth or an app password and then reads the address book the same way. The Nylas CLI lists them from your terminal: nylas contacts list returns the saved contacts for the connected Yahoo mailbox, with no IMAP scraping required.

The Nylas CLI reads contacts from your terminal with the same source model as the Contacts API. After nylas init and nylas auth login, contacts list returns 50 contacts by default and pages through everything automatically once --limit goes over 200:

# List 50 contacts (default)
nylas contacts list

# Only the saved address book, skipping auto-collected senders
nylas contacts list --source address_book --limit 100

Every contact carries a source: address_book (saved by the user), inbox (auto-collected from sent mail), or domain (the organization directory). Filter deliberately, because a busy account can hold thousands of inbox contacts the user never saved. To find a specific person rather than list everyone, contacts search matches on company, email, or phone:

# Find contacts at a company who have an email on file
nylas contacts search --company "Acme" --has-email

See the contacts list and contacts search command reference for every flag.

Yahoo contacts are sparser than cloud-provider ones: a single contact holds at most one email address and one phone number. Listing returns 50 contacts by default, and nylas contacts list --source address_book skips any auto-collected entries. Match a specific person with contacts search by email or company.

Filter Yahoo contacts

Narrow the result set with query parameters instead of paging through every contact. The list endpoint accepts the filter fields email, phone_number, source, and group, and Yahoo supports all 4 fields. The source parameter chooses between saved entries (address_book) and the contacts Nylas builds from message participants (inbox). The recurse parameter is Microsoft-only, so it has no effect across these 4 fields on a Yahoo grant.

This curl request returns contacts whose email contains jane from the user’s saved address book. Swap email for phone_number to match on a number instead, which Yahoo also supports.

RequestNode.js SDKPython SDK

curl --request GET \
  --url 'https://api.us.nylas.com/v3/grants/<NYLAS_GRANT_ID>/contacts?source=address_book&email=jane' \
  --header 'Authorization: Bearer <NYLAS_API_KEY>'

const contacts = await nylas.contacts.list({
  identifier: grantId,
  queryParams: {
    source: "address_book",
    email: "jane",
  },
});

contacts = nylas.contacts.list(
    grant_id,
    query_params={
        "source": "address_book",
        "email": "jane",
    }
)

One Yahoo-specific limit: compound source filters like source=address_book,inbox work only for IMAP and iCloud grants, not Yahoo. Pass a single source value per request on a Yahoo account.

Things to know about Yahoo contacts

Yahoo runs on IMAP and a commercial OAuth program, which shapes how a contact list behaves compared to Google or Microsoft. The 4 notes below cover the auth approval gap, token lifetimes, the IMAP sync model, and how the source filter behaves on a Yahoo grant.

Yahoo gates contacts behind a commercial agreement

Yahoo doesn’t expose contacts the way Google’s People API or Microsoft Graph do. There’s no REST contacts endpoint, so access runs over IMAP, and Yahoo requires a signed commercial agreement first. You submit a Mail API Access form, select IMAP as the required API, and sign Yahoo’s Commercial Access Agreement before OAuth access is approved. This is the biggest difference from Google and Microsoft, where you self-serve an app registration in minutes. Budget for the approval turnaround when you plan a Yahoo launch, and read Yahoo’s developer access form for the current requirements.

OAuth tokens expire after 3,600 seconds

Yahoo’s OAuth access tokens carry an expires_in of 3,600 seconds, one hour, and Yahoo issues a long-lived refresh token alongside each one. Without Nylas you’d run that refresh cycle yourself on every mailbox. Once a grant exists, the API stores the refresh token and mints new access tokens automatically, so your list calls never see an expired-token error. Note that one redirect URI registration in the Yahoo Apps dashboard can take up to 24 hours to activate, so register early during development.

Contacts sync over IMAP, not a push API

Because Yahoo is IMAP-based, contact data syncs on a poll rather than through real-time push like Google’s People API. Nylas keeps a synced copy so your list calls hit a cache instead of Yahoo’s servers on every request, which keeps reads fast and avoids tripping IMAP connection limits. Yahoo doesn’t publish its IMAP rate limits, and the same 90-day cache window that applies to Yahoo messages governs how far back synced data reaches. Don’t build a Yahoo integration that expects sub-second propagation of a contact the user just added.

App passwords skip OAuth scopes entirely

When a Yahoo grant uses an app password over Hosted IMAP instead of OAuth, there are no mail-r or mail-w scopes involved. The account holder generates a 16-character app password from Yahoo’s Account security screen, and you pass it with imap_host set to imap.mail.yahoo.com and imap_port 993. This path works for accounts with two-factor authentication enabled, but it gives you less granular control than OAuth scopes do. Yahoo documents the steps in its app password article. The contact list call is identical regardless of which auth path created the grant.

What’s next

• How to list Google contacts for the Google People API equivalent
• How to list Microsoft contacts for the Microsoft Graph equivalent
• How to search contacts to match names client-side when the endpoint has no free-text query
• How to list Yahoo email messages for reading Yahoo Mail with the same grant
• Authenticating Yahoo accounts with Nylas for OAuth setup, connectors, and app passwords