iCloud authentication

You can use the Nylas iCloud connector to connect to iCloud accounts, so you can use both the Nylas Email and Calendar APIs. iCloud provides an IMAP email service, and a WebDav/CalDav calendar service.

You can allow iCloud users to log in using generic IMAP credentials, but calendar features are not available if they use IMAP. You must both create an iCloud connector and use it for user authentication to get access to a user’s iCloud calendar.

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 Custom authentication

To authenticate users with iCloud accounts using Custom authentication, follow these steps:

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

2. Create your custom log in page as you normally would.

3. Make a Custom Auth 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.

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 20MB in size.

For more information, see the official Apple documentation.