How to list Yahoo contacts

A native Yahoo grant exposes its saved address book through CardDAV. Nylas translates that provider protocol into the same Contacts API schema used for Google, Microsoft, iCloud, and Exchange, including native create, update, delete, and explicit group membership.

Why use Nylas instead of Yahoo CardDAV directly?

One REST contract. Nylas handles CardDAV discovery, vCard parsing, conditional writes, and cursor pagination.
Safe resource routing. Nylas treats provider href values as untrusted and validates them against the address books discovered for the grant.
Normalized groups. Nylas turns explicit Yahoo group vCard records into Contact Groups and hides address-book containers.
Provider-independent code. Your application can reuse the same Contacts endpoints and object schema across supported providers.

Before you begin

You need:

A Nylas application with a valid API key.
A native Yahoo connector in the application.
A native Yahoo grant authenticated through the connector.

Use a native Yahoo grant

Native Yahoo CardDAV support belongs to the Yahoo connector. A generic hosted IMAP grant, including one authenticated with a Yahoo app password, keeps the existing hosted IMAP mailbox-derived Contact behavior and doesn’t gain CardDAV address-book access.

Follow the Yahoo authentication guide to create the native connector and grant. The Yahoo mail OAuth scopes authorize the native connector. The Contacts API doesn’t add a separate Google- or Microsoft-style Contacts scope.

List Yahoo CardDAV contacts

Call GET /v3/grants/{grant_id}/contacts. The default and supported writable source is address_book, so you can omit the source parameter or set source=address_book explicitly.

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

The native Yahoo source rules are strict:

Omitting source selects CardDAV address_book contacts.
source=inbox is available only when Nylas enables the legacy mailbox-derived feature. It’s read-only.
source=domain and compound values such as source=address_book,inbox return an invalid request error.
Offset pagination is unsupported. Use the returned next_cursor as page_token.

Create, update, and delete Yahoo contacts

The standard Contact create, update, and delete endpoints write the native Yahoo address book through CardDAV. The API selects the grant’s writable address book. If it can’t find one, or discovers more than one possible writable address book, the write fails instead of guessing.

curl --compressed --request POST \
  --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' \
  --data '{
    "birthday": "1960-12-31",
    "company_name": "Nylas",
    "emails": [
      {
        "email": "[email protected]",
        "type": "work"
      },
      {
        "email": "[email protected]",
        "type": "home"
      }
    ],
    "given_name": "Leyah",
    "groups": [
      {
        "id": "starred"
      },
      {
        "id": "friends"
      }
    ],
    "im_addresses": [
      {
        "type": "jabber",
        "im_address": "leyah_jabber"
      },
      {
        "type": "msn",
        "im_address": "leyah_msn"
      }
    ],
    "job_title": "Software Engineer",
    "manager_name": "Bill",
    "middle_name": "Allison",
    "metadata": {
      "key1": "customer-123",
      "crm_record": "crm-456"
    },
    "nickname": "Allie",
    "notes": "Loves Ramen",
    "office_location": "123 Main Street",
    "phone_numbers": [
      {
        "number": "+1-555-555-5555",
        "type": "work"
      },
      {
        "number": "+1-555-555-5556",
        "type": "home"
      }
    ],
    "physical_addresses": [
      {
        "type": "work",
        "street_address": "123 Main Street",
        "postal_code": "94107",
        "state": "CA",
        "country": "USA",
        "city": "San Francisco"
      },
      {
        "type": "home",
        "street_address": "456 Main Street",
        "postal_code": "94107",
        "state": "CA",
        "country": "USA",
        "city": "San Francisco"
      }
    ],
    "source": "address_book",
    "surname": "Miller",
    "web_pages": [
      {
        "type": "work",
        "url": "<WEBPAGE_URL>"
      },
      {
        "type": "home",
        "url": "<WEBPAGE_URL>"
      }
    ]
  }'

curl --compressed --request PUT \
  --url 'https://api.us.nylas.com/v3/grants/<NYLAS_GRANT_ID>/contacts/<CONTACT_ID>' \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer <NYLAS_API_KEY>' \
  --header 'Content-Type: application/json' \
  --data '{
    "birthday": "1960-12-31",
    "company_name": "Nylas",
    "emails": [
      {
        "email": "[email protected]",
        "type": "work"
      },
      {
        "email": "[email protected]",
        "type": "home"
      }
    ],
    "given_name": "Leyah",
    "groups": [
      {
        "id": "starred"
      },
      {
        "id": "all"
      }
    ],
    "im_addresses": [
      {
        "type": "jabber",
        "im_address": "leyah_jabber"
      },
      {
        "type": "msn",
        "im_address": "leyah_msn"
      }
    ],
    "job_title": "Software Engineer",
    "manager_name": "Bill",
    "middle_name": "Allison",
    "metadata": {
      "key1": "customer-123",
      "crm_record": "crm-789"
    },
    "nickname": "Allie",
    "notes": "Loves Ramen",
    "office_location": "123 Main Street",
    "phone_numbers": [
      {
        "number": "+1-555-555-5555",
        "type": "work"
      },
      {
        "number": "+1-555-555-5556",
        "type": "home"
      }
    ],
    "physical_addresses": [
      {
        "type": "work",
        "street_address": "123 Main Street",
        "postal_code": "94107",
        "state": "CA",
        "country": "USA",
        "city": "San Francisco"
      },
      {
        "type": "home",
        "street_address": "456 Main Street",
        "postal_code": "94107",
        "state": "CA",
        "country": "USA",
        "city": "San Francisco"
      }
    ],
    "source": "address_book",
    "surname": "Miller",
    "web_pages": [
      {
        "type": "work",
        "url": "<WEBPAGE_URL>"
      },
      {
        "type": "home",
        "url": "<WEBPAGE_URL>"
      }
    ]
  }'

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

CardDAV updates use ETag values internally for conditional writes, but the ETag isn’t part of the public Contact ID. A conflicting provider edit can produce a conflict or partial-failure error. Fetch the current contact before retrying.

Filter and paginate Yahoo contacts

Yahoo supports the email, phone_number, and group filters for CardDAV address-book contacts. Use one source per request.

Continue through the result set by passing next_cursor back as page_token:

Contact metadata filtering uses metadata_pair=key1:value. You can combine it with limit and page_token, but not with email, phone_number, group, recurse, or a non-default source. See Add metadata to a contact for create, update, clear, and cleanup behavior.

Yahoo contact and group IDs

Native contact IDs start with carddav_v1_; Contact Group IDs start with carddav_group_v1_. Both encode only the canonical provider href and apply to one grant. Treat them as opaque values and persist the latest ID from every response.

An ordinary edit keeps the same contact ID while the href remains stable. If Yahoo moves a contact, the href and ID can change. Nylas can then observe a deletion under the old ID and an update under the new ID. The API doesn’t keep an old-to-new mapping, and href reuse means the ID is a current locator rather than a permanent tombstone.

GET /contacts/groups returns only explicit group vCard records. Address-book collections are containers, not Contact Groups. Filter members with GET /contacts?group=<CONTACT_GROUP_ID>, and change membership through the Contact groups field. The API doesn’t create, rename, or delete Contact Group resources.

Yahoo rejects the filtered CardDAV addressbook-query that iCloud supports. Nylas instead performs a bounded address-book inventory and addressbook-multiget, using Yahoo’s legacy member reference properties. It doesn’t treat vCard CATEGORIES as group membership. Oversized group data or concurrent ETag changes can return a provider error; fetch current state before retrying.

Yahoo field and notification behavior

A native Yahoo contact supports at most one email address and multiple web pages.
You can’t write manager_name, office_location, or profile pictures. profile_picture=true is unsupported.
Native Yahoo grants don’t emit contact.updated or contact.deleted, including for Contacts API create, update, and delete requests. Reconcile changes by listing contacts.
Contact metadata is Nylas-owned and never written to the Yahoo vCard. Provider and metadata writes are separate and not atomic.
Invalid or cross-grant CardDAV IDs fail closed. Authentication, permission, resource-size, rate-limit, timeout, and other provider failures return provider errors.

List Yahoo contacts from the terminal

After a native Yahoo grant exists, nylas contacts list --source address_book returns its CardDAV contacts without a separate CardDAV client.

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.

What’s next

Manage contacts with the Contacts API for the shared CRUD, metadata, ID, and error contract
Work with Contact Groups for group listing, filtering, and membership examples
How to search contacts for provider and metadata filters
Yahoo authentication guide for native connector setup
How to list Yahoo email messages for Yahoo Mail with the same grant