Skip to content

Create grants with IMAP authentication

This page explains how to authenticate users to your Nylas application using IMAP auth. IMAP connections don’t require a provider auth app, and they don’t include calendar functionality.

For more information about working with IMAP accounts in Nylas, see Use IMAP accounts and data with Nylas.

New options for Yahoo, Exchange, and iCloud users

If you’re authenticating Yahoo, Exchange on-prem, or iCloud users, you can either connect them using IMAP auth or use the dedicated Nylas connectors for those providers. If you authenticate them using IMAP, you can access email data only, even if the service also provides calendar features.

If you plan to authenticate Yahoo users, you should use the Yahoo OAuth method instead of IMAP auth to improve reliability.

Create an IMAP connector

Make a POST /v3/connectors request and set provider to imap to create an IMAP connector.

You can also create the connector in the Nylas Dashboard by navigating to Connectors and clicking the plus symbol beside IMAP. Specify the settings for your connector, then Save your changes.

Create grants for IMAP users

Most IMAP providers require that you use an application password to authenticate third-party tools. If this is the case, you need to redirect the user to their provider so they can enter their app password before authenticating. Some providers use the user’s usual login credentials and don’t require app passwords.

Nylas offers Hosted OAuth and Custom Authentication for the supported IMAP providers.

Create an IMAP grant with Hosted OAuth

You can create IMAP grants using either Hosted OAuth with an API key or Hosted OAuth and an access token.

You can also start the Hosted Auth flow using the Nylas SDKs, as in the examples below.

Create an IMAP grant with Custom Authentication

If you already have your user’s password or app password, you can create a grant for them using Custom Authentication.

The example below shows how to make a Custom Authentication request with the correct provider and settings. The rest of the authentication process follows the same process as for non-IMAP grant creation.

curl -X POST 'https://api.us.nylas.com/v3/connect/custom' \
--header 'Authorization: Bearer <NYLAS_API_KEY>' \
--header 'Content-Type: application/json' \
--data-raw '{
"provider": "imap",
"settings": {
"imap_username": "<IMAP_USERNAME>",
"imap_password": "<IMAP_PASSWORD>",
"imap_host": "imap.mail.me.com",
"imap_port": 993,
"smtp_host": "smtp.mail.me.com",
"smtp_port": 465
}
}'

For more information, see the Custom auth documentation.

Error handling for IMAP Hosted authentication

Nylas creates a grant only if both the IMAP settings are validated and the provider accepts the user’s login credentials. When an error occurs, the redirect_uri includes an error_type query parameter when the auth process is complete. The possible error_type values are…

  • provider_not_responding: The IMAP provider didn’t respond to the login request from Nylas.
  • invalid_authentication: The provider responded with an incorrect credential error. Nylas prompts the user with an error message.
  • auth_limit_reached: The user entered an incorrect password three times. Nylas redirects back to your application’s redirect_uri with the error code instead of showing an error message.