Only show these results:

Use IMAP accounts and data with Nylas v3

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 an end user's IMAP provider, Nylas uses IMAP to get and monitor for new email messages, and uses SMTP (the Simple Mail Transfer Protocol) to actually send new emails. Neither of these protocols handles calendars, but some IMAP providers also offer a calendar service. Contact Nylas Support for more information on using Nylas with IMAP calendar offerings.

Before you begin

Before you can connect to an IMAP provider in Nylas v3, you need the following prerequisites:

  • Access to the Nylas v3 Dashboard.
  • An existing v3 Nylas application.

How Nylas works with IMAP

When an end user authorizes a connection to Nylas, the Nylas servers begin syncing their mailboxes, including the last 90 days of their email history. Unlike in Nylas v2, in v3 you do not receive webhook notifications about these historical email messages. The 90-day retention period is a rolling window, so email 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 they connect. These connections listen for changes to the Inbox and Sent folders. Nylas makes additional short-lived connections to download new or changed email messages, and to modify folders or their contents. These connections close before Nylas returns an API response.

Create IMAP connector

📝 Note: 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.

You can create an IMAP connector using either the v3 Dashboard or the Nylas APIs.

Create IMAP connector from v3 Dashboard

Follow these steps 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 menu, click Connectors.
  3. Find the IMAP tile and click +Add.

Create IMAP connector with v3 APIs

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

Create grants for IMAP users

Most IMAP providers require that you use an application password ("app password") to authenticate third-party tools. If this is the case, you must direct the end user to the provider so they can complete this task before authenticating. 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 do either of the following:

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 '{
    "provider": "imap",
    "settings":
    {
      "imap_username": "<ICLOUD-EMAIL>",
      "imap_password": "<ICLOUD-PASSWORD>",
      "imap_host": "imap.mail.me.com",
      "imap_port": 993,
      "type": "icloud"
    }
  }'

For more information, see the Custom auth documentation.

IMAP provider limitations

You should keep the following limitations in mind when using Nylas to work with IMAP providers:

  • 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 affect 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 (see Provider rate limits).
  • Attachment sizes are subject to individual providers' file size limits.
  • If the provider has high latency, or cannot support IMAP idle connections, webhook notifications about events on the provider are delayed.
  • Email messages stored in different folders may experience different webhook latency because of provider limitations.
  • Email messages must be encoded using UTF-8 or ASCII. Other encodings are not supported, and they might not be retrievable or might appear with an empty body.
  • All email messages must conform to the Internet Message Format (IMF), and must have the Message-ID and Reference fields at minimum. Nylas ignores malformed messages.
  • If you have email accounts on an on-premises Microsoft Exchange server, you might want to authenticate them as IMAP grants. To do so, your server must be configured to accept IMAP and SMTP connections, and must support either the PLAIN (recommended) or LOGIN authentication scheme.
  • When you use the search_query_native query parameter to list messages, the search results returned may not be what you expect due to individual provider limitations. Some examples are:
    • Yahoo IMAP search does not support NOT syntax. The search results returned might still contain the messages you want to exclude.
    • Microsoft Exchange IMAP does not support searching by the BCC field. The search results returned will not contain any results that meet your BCC query.

In v3 iCloud, Yahoo, and IMAP providers can retrieve email data up to 90 days old. For most providers, email webhook notifications are in real-time, however Yahoo and AOL accounts can take 5 minutes to deliver email webhooks. Nylas does not send webhook notifications for changes to email messages (for example folder or label changes) if the message being changed is older than 90 days.

Provider rate limits

In most cases, rate limiting for IMAP connections is configured by your administrator. For some larger providers, however, these limits are set by default.

For iCloud, there are several 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.

Yahoo doesn't publicize its sending limits for email messages. If you encounter a rate limit notification, you must wait until the limit expires to send email messages. Usually, the duration of the limit is included in the notification. For more information, see the official Yahoo documentation.

UIDVALIDITY for IMAP providers

IMAP providers use the UID field as an identifier for email messages in a folder. Technically, UIDs should not change, but this is not always the case because of the mechanics of IMAP providers.

Providers use a UIDVALIDITY field that is updated to indicate that a folder's UID has been changed. Nylas checks the UIDVALIDITY field every five minutes. When Nylas detects that the field changed, it removes all cached folder UIDs associated with the grant and re-indexes them.

Because of provider latency, the re-indexing process can take a long time. During the process, Nylas might return inconsistent or stale information.

⚠️ IMAP providers that are unable to provide reasonable response times during a UIDVALIDITY re-index are considered not supported by Nylas.

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