Nylas Docs

The Nylas Developer Hub

Welcome to the Nylas developer hub. You'll find comprehensive guides and documentation to help you start working with Nylas as quickly as possible, as well as support if you get stuck. Let's jump right in!

Developer Guide

Inconsistent UIDVALIDITY value

In some cases, Nylas must stop syncing accounts for certain IMAP servers that are incorrectly configured. If you notice that an account is stopped and there are mailsync logs in the Nylas Dashboard that look similar to this:

Resynced more than MAX_UIDINVALID_RESYNCS in a row. Stopping sync.

then unfortunately Nylas is unable to continue syncing the account. Servers that do not maintain consistent UIDVALIDITY values are incompatible with the Nylas system, and there isn't anything Nylas can do to work around this issue. Unfortunately these servers will remain unsupported until they adhere to the recommendations set forth RFC3501 regarding the UIDVALIDITY value.

When we try to sync an IMAP account, Nylas makes use of two important identifiers to link locally cached messages with those that exist on the IMAP server. These values are called UID and UIDVALIDITY according to RFC3501.

 Any change of unique identifiers between sessions MUST be detectable using the
   UIDVALIDITY mechanism discussed below.  Persistent unique identifiers
   are required for a client to resynchronize its state from a previous
   session with the server (e.g., disconnected or offline accessq
   clients); this is discussed further in IMAP-DISC https://tools.ietf.org/html/rfc3501#ref-IMAP-DISC

As you can see, it is very important that Nylas has a "persistent unique identifier" across sessions when syncing mail, to make sure data remains consistent and up to date. If there are not persistent UIDs between sessions then a UIDVALIDITY value is used to let you know your cache must be invalidated and new UIDs will be assigned to messages.

   Note: Ideally, unique identifiers SHOULD persist at all
        times.  Although this specification recognizes that failure
        to persist can be unavoidable in certain server
        environments, it STRONGLY ENCOURAGES message store
        implementation techniques that avoid this problem.  For
        example:

and

      2) If the message store has no mechanism to store unique
            identifiers, it must regenerate unique identifiers at
            each session, and each session must have a unique
            UIDVALIDITY value.

Since Nylas syncs across multiple sessions for an account and UIDVALIDITY changes constantly, there is no way for us to ever properly link IMAP UIDs since they become invalidated each session.

    Whenever the client selects a mailbox, the client must compare the
       returned UID validity value with the value stored in the local cache.
       If the UID validity values differ, the UIDs in the client's cache are
       no longer valid.

We are therefore unable to sync mail servers whose UIDVALIDITY changes constantly.

We most typically see this occurring for Courier-IMAP servers.

UIDVALIDITY AND EMPTY FOLDERS

In some cases, the UIDVALIDITY error is being triggered on empty folders that have no messages (and therefore no UIDVALIDITY value exists). In these cases, the end user can delete the empty folders as a workaround to this issue. Alternatively, the end user can put at least one message in every empty folder to generate the UIDVALIDITY value and allow the account to resync.

Inconsistent UIDVALIDITY value


Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.