Skip to main content

mailboxReset

The mailboxReset webhook event is triggered when EmailEngine has to rebuild its index for an IMAP folder from scratch. It is rare but significant: every message UID EmailEngine previously tracked for that folder is no longer meaningful.

When This Event is Triggered​

The mailboxReset event fires when:

  • The IMAP server reports a different UIDVALIDITY for the folder than the one EmailEngine stored (reason: "uidValidityChange"). Servers do this when a folder is recreated, repaired, migrated or restored from backup
  • EmailEngine's own stored index for the folder is missing while the account has synced before and the server still has messages in the folder (reason: "syncStateLost"), for example after the folder's keys were evicted from Redis

UIDVALIDITY is the IMAP mechanism that tells a client whether previously assigned UIDs are still valid. When it changes, they are not, and the folder must be fully resynchronized. A lost local index has the same practical consequence.

No message events are replayed

Rebuilding the baseline deliberately does not emit messageNew for the messages it re-indexes. Without that suppression, a reset on a large folder would replay the entire mailbox to your webhook endpoint. Treat mailboxReset itself as the signal to reconcile, and fetch the folder's messages through the API if you need them.

IMAP accounts only

Folder events are produced by the IMAP client. Gmail API and Microsoft Graph accounts do not send mailboxNew, mailboxDeleted or mailboxReset.

Payload Schema​

Top-Level Fields​

FieldTypeRequiredDescription
serviceUrlstring or nullYesThe configured EmailEngine service URL. null when the serviceUrl setting is empty
accountstringYesAccount ID the folder belongs to
datestringYesISO 8601 timestamp when the webhook was generated
pathstringYesFull path of the folder that was reset, for example INBOX
specialUsestringNoSpecial-use flag of the folder, for example \Inbox. Present only when the folder has one
eventstringYesAlways mailboxReset
dataobjectYesReset details

Reset Data Fields (data object)​

FieldTypeRequiredDescription
pathstringYesFull folder path, the same value as the top-level path
namestringYesDisplay name of the folder, the last segment of the path
specialUsestring or booleanYesSpecial-use flag such as \Inbox, or false when the folder has none
uidValiditystring or booleanYesThe folder's current UIDVALIDITY as a string, or false if the server did not report a usable one
prevUidValiditystring or booleanNoThe UIDVALIDITY EmailEngine had stored, as a string, or false if the stored value was not usable. Present only with reason: "uidValidityChange"
reasonstringYesWhy the folder was reset, see below

There is no event ID in the body. EmailEngine sends it in the X-EE-Wh-Event-Id request header. See Delivery and Retries.

Reset Reasons​

ReasonMeaning
uidValidityChangeThe server issued a new UIDVALIDITY for the folder, which invalidates every UID EmailEngine had stored
syncStateLostEmailEngine's own index for the folder was missing and had to be rebuilt from the server

Both mean the same thing for your application: the message IDs you previously stored for this folder no longer refer to those messages. Branch on reason only if you want to distinguish a server-side renumbering from a local index rebuild.

Example Payload​

IMAP Account - Inbox Reset​

{
  "serviceUrl": "https://emailengine.example.com",
  "account": "user123",
  "date": "2025-10-17T14:22:33.456Z",
  "path": "INBOX",
  "specialUse": "\\Inbox",
  "event": "mailboxReset",
  "data": {
    "path": "INBOX",
    "name": "INBOX",
    "specialUse": "\\Inbox",
    "uidValidity": "1697556153",
    "prevUidValidity": "1695234567",
    "reason": "uidValidityChange"
  }
}

Custom Folder Reset​

{
  "serviceUrl": "https://emailengine.example.com",
  "account": "support-inbox",
  "date": "2025-10-17T15:45:12.789Z",
  "path": "Support/Tickets",
  "event": "mailboxReset",
  "data": {
    "path": "Support/Tickets",
    "name": "Tickets",
    "specialUse": false,
    "uidValidity": "1697560312",
    "prevUidValidity": "1690234567",
    "reason": "uidValidityChange"
  }
}

Lost Local Index​

When the stored index was missing, there is no previous UIDVALIDITY to report and prevUidValidity is omitted:

{
  "serviceUrl": "https://emailengine.example.com",
  "account": "recovered-account",
  "date": "2025-10-17T16:30:00.000Z",
  "path": "Archive/2024",
  "event": "mailboxReset",
  "data": {
    "path": "Archive/2024",
    "name": "2024",
    "specialUse": false,
    "uidValidity": "1697564200",
    "reason": "syncStateLost"
  }
}

Handling the Event​

Every EmailEngine message ID you hold for the folder is invalid after a reset, so either discard the cached messages or mark them for revalidation and list the folder again through the API:

async function handleMailboxReset(event) {
  const { account, path, data } = event;

  // Cached IDs no longer refer to these messages
  await db.messages.updateMany({
    where: { accountId: account, folder: path },
    data: { needsRevalidation: true }
  });

  await db.folders.upsert({
    where: { accountId_path: { accountId: account, path } },
    update: { uidValidity: data.uidValidity, lastReset: new Date(event.date) },
    create: { accountId: account, path, name: data.name, uidValidity: data.uidValidity }
  });

  // Then list the folder through the API and match on the Message-ID header
  await resyncQueue.add('folder-resync', { account, path, reason: data.reason });
}

Important Considerations​

What UIDVALIDITY Means​

UIDVALIDITY is an IMAP concept that guarantees message UID uniqueness within a mailbox. When UIDVALIDITY changes:

  • All previously assigned UIDs become invalid
  • You cannot rely on old UID-to-message mappings
  • A full folder resync is required to rebuild the message list
  • Any cached message data keyed by UID should be discarded

What EmailEngine Does on a Reset​

When EmailEngine detects a UIDVALIDITY change, or finds its index for the folder missing, it:

  1. Discards the stored message index for the folder
  2. Records every message currently on the server as already seen, without sending messageNew for any of them
  3. Stores the server's current state as the new baseline
  4. Sends this webhook

Messages that arrive after the reset are reported with messageNew as usual. Nothing is sent for the messages that were in the folder at the time of the reset, so reconcile from the API rather than waiting for events.

EmailEngine Message IDs Change Too​

EmailEngine's message IDs (the id field on messages and in message events) are derived from the folder and the UID, so a reset invalidates them along with the UIDs. Match on the Message-ID header if you need to relate messages across a reset.

Rare But Important​

UIDVALIDITY changes are relatively rare in normal operation. Common causes include:

  • Mail server migration
  • Database repairs or corruption recovery
  • Server software updates that reset counters
  • Mailbox import and export operations
  • Administrative maintenance

Frequent resets on one account point at a server that reassigns UIDVALIDITY on every folder open, which is a server problem rather than something the handler can work around.

See Also​