Only show these results:
public-beta-v3

Connecting to IMAP accounts in API v3 Beta

The Nylas API v3 is in public beta. It might contain bugs, and might change before it is generally available. See the v3 Beta documentation for more information.

IMAP (the Internet Message Access Protocol) is one of the foundational protocols of the internet age. It's still commonly used both by small private email providers, and large ones such as AOL, Yahoo, and iCloud.

When you use Nylas to connect to a user's IMAP provider, Nylas uses IMAP to get and monitor for new email, and uses SMTP (Simple Mail Transfer Protocol) to actually send new email. Neither of these protocols handles calendars, however some IMAP providers also offer a calendar service. Contact Nylas Support for more information on integrating Nylas with IMAP calendar offerings.

To connect with IMAP providers in the Nylas API v3 Beta, you need access to the Nylas v3 Dashboard, a v3 Nylas application, and a v3 connector.

How Nylas works with IMAP

When the end-user authorizes a connection to Nylas, the Nylas servers begin syncing their mailboxes, including the last 90 days of that user's email history. Unlike in Nylas API v2, in v3 you do not receive webhook notifications about these historical email messages. The 90 day retention period is a rolling window, so messages are purged from the Nylas system after 90 days.

Nylas also makes two low-bandwidth "IMAP idle" connections, similar to a heartbeat, to the end-user's IMAP provider when the user connects. These connections listen for changes to the Inbox and Sent folders. Nylas makes additional short-lived connections to download new or changed messages, and to modify folders or their contents. These connections close before Nylas returns the API response.

Create an IMAP connector

Because the IMAP protocol predates the idea of delegated scopes, IMAP connectors do not require provider auth applications to connect, and they do not require that you define scopes for your Nylas connector.

Create a connector either using the Nylas API, or from the Dashboard.

To create a connector from the Dashboard:

  1. Log in to the v3 Dashboard, and navigate to the Nylas application you're creating the connector for.
  2. In the left navigation, click Connectors.
  3. Find the IMAP tile and click +Add.

To create a connector using the v3 API, make a POST /v3/connectors request. Set the provider to imap, and include a name for the connector.

Creating Grants for IMAP users

Most IMAP providers require that you use an application password or "app password" to authenticate third party tools. If this is the case, you must direct the user to the provider so they can complete this task before completing authentication. Some providers do not require app passwords, and instead use the end-user's usual login credentials.

To create a Grant for an IMAP user, you can use either hosted authentication (POST /v3/connect/auth) and direct the user to create an app password if needed, or use Custom authentication (POST /v3/connect/custom) if you have a password or app password for the user already.

The examples below show how to make these requests with the correct provider and settings. The rest of the authentication process follows the same process as for non-IMAP Grant creation.

{
  "provider": "imap",
  "redirect_uri": "http://localhost:3000",
  "settings": {
    "type": "yahoo"
  }
}   
{
  "provider": "imap",
  "settings": {
    "imap_username": "[email protected]",
    "imap_password": "johns-super-secret-app-password",
    "imap_host": "imap.mail.yahoo.com",
    "imap_port": 993,
    "type": "yahoo"
  }
}

IMAP limitations

  • Nylas, and the Nylas APIs are subject to the throughput and traffic limitations configured by each provider. This means that, especially for smaller providers, their availability can negatively impact the freshness, completeness, and availability of their data in the Nylas systems. It also means that excessive API requests might trigger rate limiting from the provider.

  • Attachment sizes are also subject to the file size limits of the individual providers.

  • If the provider has high latency or cannot support IMAP idle connections, webhook notifications about events on the provider are delayed.

  • Messages in different folders may experience different webhook latency due to provider limitations.

  • Message encoding must be UTF-8 or ASCII. Messages in other encodings are not supported and might not be retrievable, or might appear with an empty body.

  • All messages must conform to the Internet Message Format (IMF), and must have at minimum the Message-ID and Reference fields. Nylas ignores malformed messages.

IMAP and UIDVALIDITY

IMAP providers use a UID field as an identifier for messages in folder. Technically, UIDs should not change, however this is not always the case due to the mechanics of IMAP providers. The provider uses a UIDVALIDITY field that the provider changes to indicate that the folder's UID changed. Nylas checks the UIDVALIDITY field every five minutes, and when it detects a change it removes all cached folder UIDs for the account, and reindexes.

Due to provider latency the reindex process can take a long time, and Nylas might return inconsistent or stale information while the reindex is in process. IMAP providers that are unable to provide reasonable response times during a UIDVALIDITY reindex are considered not supported.

Misconfigured IMAP providers might return a different UIDVALIDITY value for every session, which makes it impossible to sync data consistently. See Troubleshooting UIDVALIDITY for more information.