Use IMAP accounts and data with Nylas

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 messages, and uses SMTP (the Simple Mail Transfer Protocol) to actually send 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.

💡 Nylas v3 also offers connectors for Yahoo, Exchange on-prem, and iCloud accounts. For more information, see the Yahoo authentication guide, the Exchange on-prem guide, and the iCloud auth guide.

How Nylas works with IMAP

When a user authorizes a connection to Nylas, the Nylas servers begin syncing their mailboxes and the last 90 days of email history. Unlike in v2, you don't receive webhook notifications for historical email messages in Nylas v3.

📝 Nylas uses a rolling 90-day retention period for IMAP messages. After 90 days, Nylas deletes its synced versions of IMAP messages. You can't retrieve these messages using the Nylas APIs after they're deleted.

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

See Create grants with IMAP authentication for information on setting up IMAP auth and creating grants for your users.

Nylas v3 no longer generates an "Emailed Events" calendar for IMAP accounts, and IMAP accounts don't have calendars natively. More specific connectors are available for Yahoo, Exchange on-prem, and iCloud if you need access to an account's calendar.

Static IP support for IMAP accounts

ℹ️ Static IP is available as an add-on for Core and Plus plans.

Some email servers in secure environments only accept connections and data from a known list of sender IP addresses. If you need to connect to a server with these settings, you can add static IP support to your Nylas plan.

When you add static IP support to your plan, Nylas uses only a specific set of static IPs when connecting your application's users. You can then provide the administrators of those email servers with an allowlist of Nylas IPs so the user can authenticate with that server.

Static IP support is currently available for IMAP. Support for Exchange on-premises servers is coming soon.

To add static IP support to your Nylas account, contact your account representative or Nylas support.

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 data in the Nylas systems. It also means that excessive API requests might trigger rate limiting from the provider.
Attachment sizes are subject to individual providers' file size limits.
If the provider has high latency, or it can't support IMAP idle connections, webhook notifications about events on the provider are delayed.
Email messages stored in different folders might experience different webhook latency because of provider limitations.
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 might not be what you expect due to individual provider limitations. Some examples are:
- Yahoo IMAP search doesn't support NOT syntax. The search results returned might still contain the messages you want to exclude.
- Microsoft Exchange IMAP doesn't support searching by the BCC field. The search results returned will not contain any results that meet your BCC query.
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.