Authenticating iCloud accounts with Nylas

You can use the Nylas iCloud connector to access iCloud Mail, Calendar, and Contacts. iCloud provides IMAP email, WebDAV/CalDAV calendars, and a CardDAV address book.

A generic hosted IMAP grant doesn’t provide iCloud Calendar or CardDAV Contacts. Create an iCloud connector and use it to authenticate a native iCloud grant for those features.

Apple requires an app-specific password when you authenticate iCloud accounts. For more information, see the app passwords documentation.

Before you begin

Before you start authenticating iCloud accounts, make sure you understand how Nylas authenticates. You also need to create at least one Nylas application.

Add an iCloud connector

1. In the Nylas Dashboard, navigate to the application you want to use iCloud with.
2. Click Connectors in the left navigation.
3. Find the iCloud item, and click the plus icon (+).

No further connector configuration is required, and iCloud doesn’t require that you request scopes.

Have the user create an app password

Next, direct your user to the Apple ID log in page and have them log in.

Have them follow the instructions to generate an app-specific password for iCloud. They will use this password when authenticating with your app instead of using their main account password.

This step must be done manually by the user, as Apple doesn’t provide an API for generating app passwords.

iCloud Hosted authentication

To authenticate your users’ iCloud accounts using Hosted auth, follow these steps:

1. Direct your user to create an iCloud app password. This step is required.
2. Redirect the user to the Nylas Hosted auth login page by making a GET /v3/connect/auth request.
3. Have the user log in using their iCloud account and the app-specific password they created.
4. Complete the auth flow by exchanging a token with the provider. The API response contains the grant ID for the user, which you can use query for their data.

iCloud Bring Your Own Authentication

To authenticate users with iCloud accounts using Bring Your Own (BYO) Authentication, follow these steps:

1. Direct your user to create an iCloud app password. This step is required.

2. Create your custom login page as you normally would.

3. Make a BYO Authentication request and provide the user’s app-specific username and password.

   curl -X POST 'https://api.us.nylas.com/v3/connect/custom' \
     --header 'Authorization: Bearer <NYLAS_API_KEY>' \
     --header 'Content-Type: application/json' \
     --data '{
       "provider": "icloud",
       "settings": {
         "username": "<ICLOUD_EMAIL_ADDRESS>",
         "password": "<ICLOUD_PASSWORD>"
       }
     }'

Nylas returns a grant ID that you then use in other queries for the user’s data.

Access iCloud Contacts

A native iCloud grant uses CardDAV for the Contacts API address_book source. Omitting source selects that address book. You can list, get, create, update, and delete contacts, list explicit Contact Groups, filter by group, and update membership through the Contact groups field.

iCloud doesn’t require a separate Contacts scope. The app-specific password on the native grant authorizes the provider connection. The legacy mailbox-derived inbox source is gated and read-only; domain and compound source filters are unsupported.

Native CardDAV Contact IDs start with carddav_v1_, and group IDs start with carddav_group_v1_. Treat both as opaque and persist the latest ID. Provider-side moves can change the href-derived ID.

Native iCloud grants can emit contact.updated and contact.deleted. The first successful poll creates a silent baseline, and later provider changes arrive after polling and processing. Duplicate notifications are possible, and the provider-sync cursor can advance before publication, so keep handlers idempotent and reconcile important state with the Contacts API.

See How to list iCloud contacts for CRUD, pagination, groups, metadata, ID, and notification examples.

iCloud provider limitations

By default, Nylas stores messages on iCloud and IMAP providers in a cache for 90 days after they’re received or created. You can access messages older than 90 days by setting the query_imap parameter to true when you make a request to the following endpoints: Get Message, Get all Messages, Get Draft, Get all Drafts, and the Attachments endpoints. This directly queries the IMAP server instead of Nylas’ cache.

Nylas doesn’t send webhook notifications for changes to messages that are older than 90 days.

iCloud rate limits

For iCloud, there are several rate limits you should keep in mind:

• You can send 1,000 messages per day.
• You can send messages to 1,000 recipients per day.
• You can include up to 500 recipients per message.
• You can send messages up to 20 MB in size.

For more information, see the official Apple documentation.

What’s next

• List iCloud Mail from the CLI - Read and filter iCloud messages from the terminal
• List and manage iCloud contacts - Use the native CardDAV address book