Version:
Only show these results:

iCloud authentication

You can use the v3 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 end 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 in v3. You also need to create at least one Nylas application.

Add an iCloud connector

  1. In the v3 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 end 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 /oauth/authorize request.
  3. Have the end 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 end 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

In Nylas v3, iCloud and IMAP providers can retrieve email data up to 90 days old. Nylas doesn't send webhook notifications for changes to email messages (for example folder or label changes) if the message being changed is older than 90 days.

iCloud rate limits

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

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

For more information, see the official Apple documentation.