emailengine-app 2.68.1 → 2.70.0

package/lib/schemas.js

@@ -5,6 +5,7 @@ const config = require('@zone-eu/wild-config');
 const { getByteSize } = require('./tools');
 const { locales } = require('./translations');
 const { LEGACY_KEYS, OAUTH_PROVIDERS } = require('./oauth2-apps');
+const { ACCOUNT_STATES } = require('./account/account-state');
 const { validateConfig: validateExternalAccountConfig } = require('./oauth/external-account-config');
 
 // Shared Joi custom validator for the gmailService external_account credential
@@ -47,6 +48,10 @@ const ADDRESS_STRATEGIES = [
 
 const accountIdSchema = Joi.string().empty('').trim().max(256).example('user123').description('Unique identifier for the email account');
 
+// All states that the account state field can expose over the API. In addition to the state
+// machine states, 'disconnected' and 'paused' are client-level display states set by imap-client
+const ACCOUNT_DISPLAY_STATES = [...Object.values(ACCOUNT_STATES), 'disconnected', 'paused'];
+
 // Allowed configuration keys
 const settingsSchema = {
     /* ──────────────  Webhooks  ────────────── */
@@ -400,6 +405,23 @@ const settingsSchema = {
         maxLogLines: Joi.number().integer().min(0).max(1000000).default(10000).description('Maximum number of log entries to retain per account')
     }).label('LogSettings'),
 
+    /* ──────────────  Error Reporting  ────────────── */
+
+    sentryEnabled: Joi.boolean()
+        .truthy('Y', 'true', '1', 'on')
+        .falsy('N', 'false', 0, '')
+        .example(false)
+        .description(
+            'Send unhandled error reports to a Sentry server. Applied at runtime, no restart needed. Ignored when the SENTRY_DSN environment variable is set'
+        ),
+
+    sentryDsn: Joi.string()
+        .uri({ scheme: ['http', 'https'], allowRelative: false })
+        .allow('', null)
+        .example('https://public-key@sentry.example.com/1')
+        .description('Sentry DSN to send error reports to. If empty, reports go to the Sentry instance run by the EmailEngine developers')
+        .label('SentryDsn'),
+
     /* ──────────────  Local Address Strategy  ────────────── */
 
     imapStrategy: Joi.string()
@@ -932,10 +954,27 @@ const attachmentSchema = Joi.object({
     method: Joi.string().example('REQUEST').description('Calendar method (REQUEST, REPLY, CANCEL, etc.) for iCalendar attachments')
 }).label('AttachmentEntry');
 
-const AddressListSchema = Joi.array().items(addressSchema.label('RcptAddressEntry')).description('List of email addresses').label('AddressList');
+// Response-side address entry. Mail servers can return name-only entries (empty address) and
+// group-syntax artifacts (e.g. "undisclosed-recipients@") that are not valid email addresses,
+// so this is laxer than the request-side addressSchema.
+const responseAddressSchema = Joi.object({
+    name: Joi.string().trim().empty('').max(256).example('Some Name').description('Display name for the email address'),
+    address: Joi.string().allow('').example('user@example.com').description('Email address (can be empty for name-only entries)')
+})
+    .description('Email address with optional display name')
+    .label('EmailAddressResponse');
+
+const AddressListSchema = Joi.array().items(responseAddressSchema.label('RcptAddressEntry')).description('List of email addresses').label('AddressList');
 
+// Request-side sender address - keeps strict email validation
 const fromAddressSchema = addressSchema.example({ name: 'From Me', address: 'sender@example.com' }).description('Sender email address').label('FromAddress');
 
+// Response-side sender address - lax, see responseAddressSchema
+const responseFromAddressSchema = responseAddressSchema
+    .example({ name: 'From Me', address: 'sender@example.com' })
+    .description('Sender email address')
+    .label('FromAddressResponse');
+
 const emailIdSchema = Joi.string()
     .max(256)
     .example('1278455344230334865')
@@ -947,23 +986,56 @@ const threadIdSchema = Joi.string()
     .description('Thread identifier for email conversations (when supported by the email server)')
     .label('MessageThreadId');
 
+const messageSpecialUseSchema = Joi.string()
+    .example('\\Sent')
+    .valid('\\Drafts', '\\Junk', '\\Sent', '\\Trash', '\\Inbox')
+    .description('Special folder type where this message is stored')
+    .label('MessageSpecialUse');
+
+const messageCategorySchema = Joi.string()
+    .example('primary')
+    .valid('primary', 'social', 'promotions', 'updates', 'forums')
+    .description('Gmail inbox tab/category of the message (Gmail API accounts only)')
+    .label('MessageCategory');
+
+const bounceListSchema = Joi.array()
+    .items(
+        Joi.object({
+            message: Joi.string().max(256).required().example('AAAAAQAACnA').description('EmailEngine identifier of the bounce notification'),
+            recipient: Joi.string().email().example('recipient@example.com').description('Email address that bounced'),
+            action: Joi.string().example('failed').description('Bounce action (failed, delayed, etc.)').label('BounceAction'),
+            response: Joi.object({
+                message: Joi.string().example('550 5.1.1 No such user').description('Error message from the receiving server'),
+                status: Joi.string().example('5.1.1').description('SMTP status code')
+            }).label('BounceResponse'),
+            date: Joi.date().iso().example('2021-03-22T13:13:31.000Z').description('When the bounce was detected')
+        }).label('BounceEntry')
+    )
+    .description('Bounce notifications detected for this message (IMAP accounts only)')
+    .label('BounceList');
+
 const messageEntrySchema = Joi.object({
     id: Joi.string().example('AAAAAgAACrI').description('EmailEngine message identifier').label('MessageEntryId'),
-    uid: Joi.number().integer().example(12345).description('IMAP UID (unique identifier within the mailbox)').label('MessageUid'),
+    uid: Joi.number().integer().example(12345).description('IMAP UID (unique identifier within the mailbox). IMAP accounts only').label('MessageUid'),
     emailId: emailIdSchema,
     threadId: threadIdSchema,
+    path: Joi.string()
+        .example('INBOX')
+        .description(
+            'Mailbox folder path that contains this message. Returned when listing a virtual folder like "\\\\All" or when extended info is requested'
+        ),
     date: Joi.date().iso().example('2021-03-22T13:13:31.000Z').description('Date when the message was received by the mail server'),
     draft: Joi.boolean().example(false).description('Whether this message is a draft'),
     unseen: Joi.boolean().example(true).description('Whether this message is unread'),
     flagged: Joi.boolean().example(true).description('Whether this message is flagged/starred'),
+    answered: Joi.boolean().example(false).description('Whether this message has been answered (IMAP accounts only)'),
     size: Joi.number().integer().example(1040).description('Message size in bytes'),
     subject: Joi.string().allow('').example('What a wonderful message').description('Message subject line'),
 
-    from: fromAddressSchema,
+    from: responseFromAddressSchema,
     replyTo: AddressListSchema,
     to: AddressListSchema,
     cc: AddressListSchema,
-    bcc: AddressListSchema,
     messageId: Joi.string().example('<test123@example.com>').description('Message-ID header value'),
     inReplyTo: Joi.string().example('<7JBUMt0WOn+_==MOkaCOQ@mail.gmail.com>').description('Message-ID of the message this is replying to'),
 
@@ -982,29 +1054,30 @@ const messageEntrySchema = Joi.object({
             .label('TextEncodedSize')
     }).label('TextInfo'),
 
-    preview: Joi.string().description('Short preview of the message content')
-}).label('MessageListEntry');
+    preview: Joi.string().description('Short preview of the message content'),
 
-const messageSpecialUseSchema = Joi.string()
-    .example('\\Sent')
-    .valid('\\Drafts', '\\Junk', '\\Sent', '\\Trash', '\\Inbox')
-    .description('Special folder type where this message is stored')
-    .label('MessageSpecialUse');
+    category: messageCategorySchema,
+    messageSpecialUse: messageSpecialUseSchema,
+    isAutoReply: Joi.boolean().example(false).description('Whether this message appears to be an automatic reply (out of office, vacation responder, etc.)'),
+    bounces: bounceListSchema
+}).label('MessageListEntry');
 
 const messageDetailsSchema = Joi.object({
     id: Joi.string().example('AAAAAgAACrI').description('EmailEngine message identifier').label('MessageEntryId'),
-    uid: Joi.number().integer().example(12345).description('IMAP UID (unique identifier within the mailbox)').label('MessageUid'),
+    uid: Joi.number().integer().example(12345).description('IMAP UID (unique identifier within the mailbox). IMAP accounts only').label('MessageUid'),
     emailId: emailIdSchema,
     threadId: threadIdSchema,
+    path: Joi.string().example('INBOX').description('Mailbox folder path that contains this message. Not returned for Gmail API accounts'),
     date: Joi.date().iso().example('2021-03-22T13:13:31.000Z').description('Date when the message was received by the mail server'),
     draft: Joi.boolean().example(false).description('Whether this message is a draft'),
     unseen: Joi.boolean().example(true).description('Whether this message is unread'),
     flagged: Joi.boolean().example(true).description('Whether this message is flagged/starred'),
-    size: Joi.number().integer().example(1040).description('Message size in bytes'),
+    answered: Joi.boolean().example(false).description('Whether this message has been answered (IMAP accounts only)'),
+    size: Joi.number().integer().example(1040).description('Message size in bytes. Not returned for MS Graph API accounts'),
     subject: Joi.string().allow('').example('What a wonderful message').description('Message subject line'),
 
-    from: fromAddressSchema,
-    sender: fromAddressSchema,
+    from: responseFromAddressSchema,
+    sender: responseFromAddressSchema,
 
     to: AddressListSchema,
 
@@ -1024,9 +1097,7 @@ const messageDetailsSchema = Joi.object({
     headers: Joi.object()
         .example({ from: ['From Me <sender@example.com>'], subject: ['What a wonderful message'] })
         .label('MessageHeaders')
-        .description(
-            'Raw email headers as key-value pairs (arrays contain multiple values for headers that appear multiple times). Not available for MS Graph API.'
-        )
+        .description('Raw email headers as key-value pairs (arrays contain multiple values for headers that appear multiple times)')
         .unknown(),
 
     text: Joi.object({
@@ -1039,100 +1110,136 @@ const messageDetailsSchema = Joi.object({
             .label('TextDetailEncodedSize'),
         plain: Joi.string().example('Hello from myself!').description('Plain text version of the message'),
         html: Joi.string().example('<p>Hello from myself!</p>').description('HTML version of the message'),
-        hasMore: Joi.boolean().example(false).description('Whether the message content was truncated (true if more content is available via separate API call)')
+        hasMore: Joi.boolean()
+            .example(false)
+            .description('Whether the message content was truncated (true if more content is available via separate API call)'),
+        webSafe: Joi.boolean()
+            .example(true)
+            .description('Whether the HTML content has been processed into a web-safe version (set when webSafeHtml was requested)')
     }).label('TextInfoDetails'),
 
-    bounces: Joi.array()
-        .items(
-            Joi.object({
-                message: Joi.string().max(256).required().example('AAAAAQAACnA').description('EmailEngine identifier of the bounce notification'),
-                recipient: Joi.string().email().example('recipient@example.com').description('Email address that bounced'),
-                action: Joi.string().example('failed').description('Bounce action (failed, delayed, etc.)').label('BounceAction'),
-                response: Joi.object({
-                    message: Joi.string().example('550 5.1.1 No such user').description('Error message from the receiving server'),
-                    status: Joi.string().example('5.1.1').description('SMTP status code')
-                }).label('BounceResponse'),
-                date: Joi.date().iso().example('2021-03-22T13:13:31.000Z').description('When the bounce was detected')
-            }).label('BounceEntry')
-        )
-        .label('BounceList'),
+    bounces: bounceListSchema,
 
     isAutoReply: Joi.boolean().example(false).description('Whether this message appears to be an automatic reply (out of office, vacation responder, etc.)'),
 
+    preview: Joi.string().description('Short preview of the message content (Gmail API and MS Graph API accounts only)'),
+    category: messageCategorySchema,
+
     specialUse: Joi.string()
         .example('\\Sent')
         .valid('\\All', '\\Archive', '\\Drafts', '\\Flagged', '\\Junk', '\\Sent', '\\Trash', '\\Inbox')
-        .description('Special folder type of the mailbox containing this message')
+        .description('Special folder type of the mailbox containing this message (IMAP accounts only)')
         .label('MailboxSpecialUse'),
     messageSpecialUse: messageSpecialUseSchema
 }).label('MessageDetails');
 
+// Combined Document Store query echoed back by search endpoints when the (hidden) exposeQuery
+// query parameter is enabled. Free-form object, mirrors whatever was sent to the backing index
+const documentStoreQuerySchema = Joi.object()
+    .unknown()
+    .description('Combined Document Store query. Only present when the exposeQuery query parameter is enabled')
+    .label('ExposedDocumentStoreQuery')
+    .meta({ swaggerHidden: true });
+
 const messageListSchema = Joi.object({
     total: Joi.number()
         .integer()
         .example(120)
-        .description('Total number of messages matching the query (exact for IMAP, approximate for Gmail API)')
+        .description(
+            'Total number of messages matching the query (exact for IMAP, approximate for Gmail API, can be omitted for MS Graph API and Outlook search results)'
+        )
         .label('TotalNumber'),
     page: Joi.number().integer().example(0).description('Current page number (zero-based)').label('PageNumber'),
-    pages: Joi.number().integer().example(24).description('Total number of pages available (exact for IMAP, approximate for Gmail API)').label('PagesNumber'),
+    pages: Joi.number()
+        .integer()
+        .example(24)
+        .description('Total number of pages available (exact for IMAP, approximate for Gmail API, can be omitted for MS Graph API and Outlook search results)')
+        .label('PagesNumber'),
     nextPageCursor: Joi.string()
         .allow(null)
         .example('imap_kcQIji3UobDDTxc')
         .description('Cursor for fetching the next page (null when no more pages)')
         .label('NextPageCursor'),
     prevPageCursor: Joi.string().allow(null).example('imap_kcQIji3UobDDTxc').description('Cursor for fetching the previous page').label('PrevPageCursor'),
-    messages: Joi.array().items(messageEntrySchema).label('PageMessages')
+    messages: Joi.array().items(messageEntrySchema).label('PageMessages'),
+    documentStoreQuery: documentStoreQuerySchema
 }).label('MessageList');
 
+// Fields shared by both mailbox listing item shapes (the full listing and the short listing in
+// the account verification response). Joi schema instances are immutable, so the same field
+// instances are safely referenced from both objects
+const mailboxBaseFields = {
+    path: Joi.string().required().example('Kalender/S&APw-nnip&AOQ-evad').description('Full path to the mailbox').label('MailboxPath'),
+    delimiter: Joi.string()
+        .allow(null)
+        .example('/')
+        .description('Hierarchy delimiter character used in paths (can be null when the server uses a NIL delimiter)'),
+    parentPath: Joi.string()
+        .allow('')
+        .example('Kalender')
+        .description('Path to the parent mailbox. Not set (or empty) for root level mailboxes')
+        .label('MailboxParentPath'),
+    name: Joi.string().required().example('Sünnipäevad').description('Display name of the mailbox').label('MailboxName'),
+    listed: Joi.boolean().example(true).description('Whether this mailbox appears in LIST command results').label('MailboxListed'),
+    subscribed: Joi.boolean().example(true).description('Whether the user is subscribed to this mailbox').label('MailboxSubscribed'),
+    specialUse: Joi.string()
+        .example('\\Sent')
+        .valid('\\All', '\\Archive', '\\Drafts', '\\Flagged', '\\Junk', '\\Sent', '\\Trash', '\\Inbox')
+        .description('Special folder type (Inbox, Sent, Drafts, etc.)')
+        .label('MailboxSpecialUse'),
+    specialUseSource: Joi.string()
+        .example('extension')
+        .valid('user', 'extension', 'name')
+        .description('How the special use was determined: "user" (set via API), "extension" (server-provided), or "name" (guessed from folder name)')
+        .label('MailboxSpecialUseSource'),
+    noInferiors: Joi.boolean().example(false).description('Whether this mailbox can contain child mailboxes').label('MailboxNoInferiors')
+};
+
 const mailboxesSchema = Joi.array()
     .items(
         Joi.object({
-            path: Joi.string().required().example('Kalender/S&APw-nnip&AOQ-evad').description('Full path to the mailbox').label('MailboxPath'),
-            delimiter: Joi.string().example('/').description('Hierarchy delimiter character used in paths'),
-            parentPath: Joi.string().required().example('Kalender').description('Path to the parent mailbox').label('MailboxParentPath'),
-            name: Joi.string().required().example('Sünnipäevad').description('Display name of the mailbox').label('MailboxName'),
-            listed: Joi.boolean().example(true).description('Whether this mailbox appears in LIST command results').label('MailboxListed'),
-            subscribed: Joi.boolean().example(true).description('Whether the user is subscribed to this mailbox').label('MailboxSubscribed'),
-            specialUse: Joi.string()
-                .example('\\Sent')
-                .valid('\\All', '\\Archive', '\\Drafts', '\\Flagged', '\\Junk', '\\Sent', '\\Trash', '\\Inbox')
-                .description('Special folder type (Inbox, Sent, Drafts, etc.)')
-                .label('MailboxSpecialUse'),
-            specialUseSource: Joi.string()
-                .example('extension')
-                .valid('user', 'extension', 'name')
-                .description('How the special use was determined: "user" (set via API), "extension" (server-provided), or "name" (guessed from folder name)')
-                .label('MailboxSpecialUseSource'),
-            noInferiors: Joi.boolean().example(false).description('Whether this mailbox can contain child mailboxes').label('MailboxNoInferiors'),
-            messages: Joi.number().integer().example(120).description('Total number of messages in the mailbox').label('MailboxMessages'),
-            uidNext: Joi.number().integer().example(121).description('Next UID value that will be assigned').label('MailboxUidNext'),
+            path: mailboxBaseFields.path,
+            id: Joi.string()
+                .example('AAMkAGVmMDEzMTM4LTZmYWUtNDdkNC1hMDZiLTU1OGY5OTZhYmY4OAAuAAAAAAAiQ8W967B7TKBjgx9rVEURAQAiIsqMbYjsT5e-T7KzowPTAAAAAAEMAAA=')
+                .description('Stable folder ID (Gmail API and MS Graph API accounts only)')
+                .label('MailboxId'),
+            delimiter: mailboxBaseFields.delimiter,
+            parentPath: mailboxBaseFields.parentPath,
+            name: mailboxBaseFields.name,
+            listed: mailboxBaseFields.listed,
+            subscribed: mailboxBaseFields.subscribed,
+            noSelect: Joi.boolean()
+                .example(false)
+                .description('Whether this mailbox can not be selected (virtual folders like "\\\\All")')
+                .label('MailboxNoSelect'),
+            specialUse: mailboxBaseFields.specialUse,
+            specialUseSource: mailboxBaseFields.specialUseSource,
+            noInferiors: mailboxBaseFields.noInferiors,
+            messages: Joi.number()
+                .integer()
+                .allow(false)
+                .example(120)
+                .description('Total number of messages in the mailbox. False if the count is not known')
+                .label('MailboxMessages'),
+            uidNext: Joi.number()
+                .integer()
+                .allow(false)
+                .example(121)
+                .description('Next UID value that will be assigned. False if the value is not known')
+                .label('MailboxUidNext'),
             status: Joi.object({
                 messages: Joi.number().integer().example(120).description('Message count from STATUS command').label('StatusMessages'),
-                unseen: Joi.number().integer().example(120).description('Unread message count from STATUS command').label('StatusUnseenMessages')
+                unseen: Joi.number().integer().example(120).description('Unread message count from STATUS command').label('StatusUnseenMessages'),
+                error: Joi.string().description('Error message if the STATUS command failed for this mailbox').label('StatusError')
             })
+                .unknown()
                 .description('Additional mailbox statistics')
                 .label('MailboxResponseStatus')
         }).label('MailboxResponseItem')
     )
     .label('MailboxesList');
 
-const shortMailboxesSchema = Joi.array()
-    .items(
-        Joi.object({
-            path: Joi.string().required().example('Kalender/S&APw-nnip&AOQ-evad').description('Full path to the mailbox').label('MailboxPath'),
-            delimiter: Joi.string().example('/').description('Hierarchy delimiter character used in paths'),
-            parentPath: Joi.string().required().example('Kalender').description('Path to the parent mailbox').label('MailboxParentPath'),
-            name: Joi.string().required().example('Sünnipäevad').description('Display name of the mailbox').label('MailboxName'),
-            listed: Joi.boolean().example(true).description('Whether this mailbox appears in LIST command results').label('MailboxListed'),
-            subscribed: Joi.boolean().example(true).description('Whether the user is subscribed to this mailbox').label('MailboxSubscribed'),
-            specialUse: Joi.string()
-                .example('\\Sent')
-                .valid('\\All', '\\Archive', '\\Drafts', '\\Flagged', '\\Junk', '\\Sent', '\\Trash', '\\Inbox')
-                .description('Special folder type (Inbox, Sent, Drafts, etc.)')
-                .label('MailboxSpecialUse')
-        }).label('MailboxShortResponseItem')
-    )
-    .label('ShortMailboxes');
+const shortMailboxesSchema = Joi.array().items(Joi.object(mailboxBaseFields).label('MailboxShortResponseItem')).label('ShortMailboxes');
 
 const licenseSchema = Joi.object({
     active: Joi.boolean().example(true).description('Whether a valid license is currently active'),
@@ -1142,7 +1249,10 @@ const licenseSchema = Joi.object({
         key: Joi.string().hex().example('1edf01e35e75ed3425808eba').description('License key'),
         licensedTo: Joi.string().example('Kreata OÜ').description('Organization or individual the license is issued to'),
         hostname: Joi.string().example('emailengine.example.com').description('Licensed hostname or environment'),
-        created: Joi.date().example('2021-10-13T07:47:42.695Z').description('License creation date')
+        created: Joi.date().example('2021-10-13T07:47:42.695Z').description('License creation date'),
+        trial: Joi.boolean().example(false).description('Whether this is a trial license'),
+        lt: Joi.boolean().example(false).description('Whether this is a lifetime license'),
+        expires: Joi.date().iso().example('2026-01-01T00:00:00.000Z').description('License expiration time, if the license is time-limited')
     })
         .allow(false)
         .label('LicenseDetails'),
@@ -1153,8 +1263,11 @@ const lastErrorSchema = Joi.object({
     response: Joi.string()
         .example('Token request failed for gmail (refresh_token, HTTP 400): invalid_grant - Token has been expired or revoked.')
         .description('Human-readable error message'),
+    description: Joi.string().example('Authentication failed').description('Additional details about the error'),
     serverResponseCode: Joi.string().example('OauthRenewError').description('Error code or classification'),
     tokenRequest: Joi.object({
+        url: Joi.string().example('https://oauth2.googleapis.com/token').description('OAuth2 token endpoint URL').label('OAuthTokenUrl'),
+        method: Joi.string().example('post').description('HTTP method used for the token request').label('OAuthTokenMethod'),
         grant: Joi.string()
             .valid('refresh_token', 'authorization_code')
             .example('refresh_token')
@@ -1166,6 +1279,42 @@ const lastErrorSchema = Joi.object({
             .example('1023289917884-h3nu00e9cb7h252e24c23sv19l8k57ah.apps.googleusercontent.com')
             .description('OAuth2 client ID used for authentication')
             .label('OAuthClientId'),
+        clientSecret: Joi.string()
+            .example('GOCSPX...V-Da')
+            .description('Partially masked OAuth2 client secret, included when the OAuth2 server indicates an invalid client secret')
+            .label('OAuthClientSecretPartial'),
+        authority: Joi.string().example('common').description('Microsoft tenant configuration (Outlook applications only)').label('OAuthAuthority'),
+        serviceClient: Joi.string()
+            .example('113328088575113530522')
+            .description('Service client ID (2-legged OAuth2 applications only)')
+            .label('OAuthServiceClient'),
+        signer: Joi.string().example('serviceKey').description('Signing method used for service account token requests').label('OAuthSigner'),
+        googleProjectId: Joi.string()
+            .example('project-name-425411')
+            .description('Google Cloud project ID (Gmail service applications only)')
+            .label('OAuthGoogleProjectId'),
+        serviceClientEmail: Joi.string()
+            .example('service-account@project-name-425411.iam.gserviceaccount.com')
+            .description('Service account email (Gmail service applications only)')
+            .label('OAuthServiceClientEmail'),
+        code: Joi.string()
+            .example('AAABhaBPHscAAAAH')
+            .description('Value of the authorization code or error code related to the failure')
+            .label('OAuthTokenErrorCode'),
+        flag: Joi.object({
+            message: Joi.string().example('Please verify the OAuth2 application credentials').description('Description of the application-level problem'),
+            code: Joi.string().example('INVALID_CLIENT_SECRET').description('Machine-readable code of the application-level problem'),
+            url: Joi.string().example('https://console.developers.google.com/').description('Link with instructions to resolve the problem')
+        })
+            .unknown()
+            .description('Application-level error flag raised by this failure')
+            .label('OAuthTokenErrorFlag'),
+        userFlag: Joi.object({
+            message: Joi.string().example('The grant for this account has been revoked').description('Description of the account-level problem')
+        })
+            .unknown()
+            .description('Account-level error flag raised by this failure')
+            .label('OAuthTokenUserFlag'),
         scopes: Joi.array()
             .items(Joi.string().example('https://mail.google.com/').label('ScopeEntry').description('OAuth2 permission scope'))
             .description('Requested OAuth2 permission scopes')
@@ -1285,6 +1434,23 @@ const searchSchema = Joi.object({
 
     gmailRaw: Joi.string().max(1024).example('has:attachment in:unread').description('Gmail search syntax (only works with Gmail accounts)'),
 
+    labels: Joi.object({
+        has: Joi.array()
+            .items(Joi.string().max(128))
+            .single()
+            .description('Match messages that contain ALL of these labels/categories. Supported for Gmail and MS Graph (Outlook) accounts only.')
+            .example(['Horizon'])
+            .label('HasLabels'),
+        not: Joi.array()
+            .items(Joi.string().max(128))
+            .single()
+            .description('Match messages that contain NONE of these labels/categories. Supported for Gmail and MS Graph (Outlook) accounts only.')
+            .example(['Horizon'])
+            .label('NotLabels')
+    })
+        .description('Filter by Gmail labels or MS Graph (Outlook) categories. Not supported for generic IMAP accounts.')
+        .label('LabelFilter'),
+
     emailIds: Joi.array()
         .items(emailIdSchema)
         .single()
@@ -1855,6 +2021,13 @@ const ipSchema = Joi.string()
     })
     .example('127.0.0.1');
 
+const tokenIdSchema = Joi.string()
+    .length(64)
+    .hex()
+    .example('1bc12baf7f0d5e51fe0a4e0eda06e1be5b8d6cc2c66b95dc0fbe4d2e9f5d5e1a')
+    .description('Token identifier (SHA-256 hash of the token)')
+    .label('TokenId');
+
 const accountCountersSchema = Joi.object({
     events: Joi.object()
         .unknown()
@@ -1885,7 +2058,7 @@ const defaultAccountTypeSchema = Joi.string()
 const outboxEntrySchema = Joi.object({
     queueId: Joi.string().example('1869c5692565f756b33').description('Unique queue entry identifier'),
     account: accountIdSchema.required(),
-    source: Joi.string().example('smtp').valid('smtp', 'api').description('How this message entered the queue').label('OutboxSource'),
+    source: Joi.string().example('smtp').valid('smtp', 'api', 'test', 'ui').description('How this message entered the queue').label('OutboxSource'),
 
     messageId: Joi.string().max(996).example('<test123@example.com>').description('Message-ID header value'),
     envelope: Joi.object({
@@ -1896,25 +2069,50 @@ const outboxEntrySchema = Joi.object({
         .label('OutboxEnvelope'),
 
     subject: Joi.string()
-        .allow('')
+        .allow('', null)
         .max(10 * 1024)
         .example('What a wonderful message')
         .description('Email subject line'),
 
+    gateway: Joi.string().allow(null).max(256).example(null).description('Gateway ID used for delivery, or null when no gateway is set'),
+    proxy: Joi.string().allow(null).example(null).description('Proxy URL used for delivery, or null when no proxy is set'),
+    localAddress: Joi.string().allow(null).example(null).description('Local IP address used for delivery, or null when not set'),
+    idempotencyKey: Joi.string().allow(null).max(1024).description('Idempotency key provided when the message was submitted'),
+    useStructuredFormat: Joi.boolean().description('Whether delivery errors for this message are reported in a structured format'),
+
     created: Joi.date().iso().example('2021-02-17T13:43:18.860Z').description('When this message was added to the queue'),
     scheduled: Joi.date().iso().example('2021-02-17T13:43:18.860Z').description('Scheduled delivery time'),
-    nextAttempt: Joi.date().iso().example('2021-02-17T13:43:18.860Z').description('Next delivery attempt time'),
+    nextAttempt: Joi.date()
+        .iso()
+        .allow(false)
+        .example('2021-02-17T13:43:18.860Z')
+        .description(
+            'Next delivery attempt time (approximate, computed from the retry backoff without jitter). False when all delivery attempts have been used up'
+        ),
 
     attemptsMade: Joi.number().integer().example(3).description('Number of delivery attempts made'),
     attempts: Joi.number().integer().example(3).description('Maximum delivery attempts before marking as failed'),
 
     progress: Joi.object({
-        status: Joi.string().valid('queued', 'processing', 'submitted', 'error').example('queued').description('Current delivery status').label('OutboxStatus'),
-        response: Joi.string().example('250 Message Accepted').description('SMTP server response (when status is "processing")'),
+        status: Joi.string()
+            .valid('queued', 'processing', 'smtp-starting', 'smtp-completed', 'submitted', 'error')
+            .example('queued')
+            .description('Current delivery status')
+            .label('OutboxStatus'),
+        response: Joi.string().example('250 Message Accepted').description('SMTP server response (when status is "submitted" or "smtp-completed")'),
+        messageId: Joi.string().example('<test123@example.com>').description('Message-ID header value of the sent message (when status is "smtp-completed")'),
+        originalMessageId: Joi.string()
+            .example('<test123@example.com>')
+            .description('Original Message-ID header value if the server assigned a new one (when status is "smtp-completed")'),
         error: Joi.object({
             message: Joi.string().example('Authentication failed').description('Error description'),
             code: Joi.string().example('EAUTH').description('Error code'),
-            statusCode: Joi.string().example(502).description('SMTP response code')
+            statusCode: Joi.number().integer().example(502).description('SMTP response code'),
+            networkRouting: Joi.object()
+                .unknown()
+                .allow(null)
+                .description('Network routing information for the failed delivery attempt')
+                .label('OutboxErrorNetworkRouting')
         })
             .label('OutboxListProgressError')
             .description('Error details (when status is "error")')
@@ -2011,7 +2209,7 @@ const exportRequestSchema = Joi.object({
         .valid('plain', 'html', '*')
         .default('*')
         .example('*')
-        .description('Text content to include: "plain", "html", "*" (both), or omit for metadata only')
+        .description('Text content to include: "plain", "html", or "*" (both)')
         .label('ExportTextType'),
     maxBytes: Joi.number()
         .integer()
@@ -2058,7 +2256,9 @@ const exportStatusSchema = Joi.object({
     progress: exportProgressSchema,
     created: Joi.date().iso().example('2024-01-15T10:30:00Z').description('When export was created'),
     expiresAt: Joi.date().iso().example('2024-01-16T10:30:00Z').description('When export file expires'),
-    truncated: Joi.boolean().example(true).description('Whether the export was truncated due to message count or size limits'),
+    truncated: Joi.boolean()
+        .example(true)
+        .description('Whether the export was truncated due to message count or size limits. Only present (as true) for truncated exports'),
     error: Joi.string().allow(null).description('Error message if export failed')
 }).label('ExportStatus');
 
@@ -2087,8 +2287,146 @@ const exportIdSchema = Joi.string()
     .description('Export job identifier')
     .label('ExportId');
 
+// Boom-style error payloads returned by failed API requests. These schemas are used for API
+// documentation only - they are rendered as error response examples in Swagger UI through the
+// plugins['hapi-swagger'].responses route option and are never used to validate or modify
+// actual responses at runtime.
+
+// Builds one documented error response: a response description (shown next to the status code
+// in Swagger UI) paired with a labeled Joi schema for the Boom-style error payload. The
+// optional extra fields document values that EmailEngine adds to the base
+// { statusCode, error, message } payload for that error type.
+const errorResponseEntry = ({ statusCode, statusText, messageExample, label, title, description, fields }) => ({
+    description,
+    schema: Joi.object({
+        statusCode: Joi.number().integer().example(statusCode).description('HTTP status code'),
+        error: Joi.string().example(statusText).description('HTTP status text'),
+        message: Joi.string().example(messageExample).description('Error message'),
+        ...fields
+    })
+        .label(label)
+        .description(title)
+});
+
+const errorResponseSchemas = {
+    400: errorResponseEntry({
+        statusCode: 400,
+        statusText: 'Bad Request',
+        messageExample: 'Invalid input',
+        label: 'ValidationErrorResponse',
+        title: 'Validation error',
+        description: 'Invalid input - the path parameters, query arguments, or request payload did not pass validation',
+        fields: {
+            fields: Joi.array()
+                .items(
+                    Joi.object({
+                        message: Joi.string().example('"pageSize" must be less than or equal to 1000').description('Description of the validation failure'),
+                        key: Joi.string().example('pageSize').description('Name of the input field that failed validation')
+                    }).label('ValidationErrorField')
+                )
+                .description('List of input fields that failed validation')
+                .label('ValidationErrorFields')
+        }
+    }),
+
+    401: errorResponseEntry({
+        statusCode: 401,
+        statusText: 'Unauthorized',
+        messageExample: 'Missing authentication',
+        label: 'AuthenticationErrorResponse',
+        title: 'Authentication error',
+        description: 'Authentication failed - the access token is missing, invalid, or was not accepted'
+    }),
+
+    403: errorResponseEntry({
+        statusCode: 403,
+        statusText: 'Forbidden',
+        messageExample: 'Unauthorized scope',
+        label: 'AccessDeniedErrorResponse',
+        title: 'Access denied error',
+        description: 'Access denied - the access token does not grant permission for this operation (token scope, account, or IP address restriction)'
+    }),
+
+    404: errorResponseEntry({
+        statusCode: 404,
+        statusText: 'Not Found',
+        messageExample: 'Requested message was not found',
+        label: 'NotFoundErrorResponse',
+        title: 'Not found error',
+        description: 'Not found - the requested entity (account, message, mailbox, etc.) does not exist',
+        fields: {
+            code: Joi.string().example('MessageNotFound').description('Machine-readable error code')
+        }
+    }),
+
+    422: errorResponseEntry({
+        statusCode: 422,
+        statusText: 'Unprocessable Entity',
+        messageExample: 'The mail server does not support the requested operation',
+        label: 'UnprocessableErrorResponse',
+        title: 'Unprocessable request error',
+        description: 'Unprocessable request - the request is well-formed, but the email server cannot perform the requested operation',
+        fields: {
+            code: Joi.string().example('MissingServerExtension').description('Machine-readable error code')
+        }
+    }),
+
+    429: errorResponseEntry({
+        statusCode: 429,
+        statusText: 'Too Many Requests',
+        messageExample: 'Rate limit exceeded',
+        label: 'RateLimitErrorResponse',
+        title: 'Rate limit error',
+        description: 'Rate limit exceeded - too many requests were made with this access token',
+        fields: {
+            ttl: Joi.number().integer().example(30).description('Seconds until the rate limit window resets')
+        }
+    }),
+
+    500: errorResponseEntry({
+        statusCode: 500,
+        statusText: 'Internal Server Error',
+        messageExample: 'An internal server error occurred',
+        label: 'InternalErrorResponse',
+        title: 'Internal server error',
+        description: 'Internal server error - an unexpected error occurred while processing the request',
+        fields: {
+            code: Joi.string().example('InternalError').description('Machine-readable error code, if available'),
+            details: Joi.any().description('Additional error details, if available')
+        }
+    }),
+
+    503: errorResponseEntry({
+        statusCode: 503,
+        statusText: 'Service Unavailable',
+        messageExample: 'No active handler for requested account. Try again later.',
+        label: 'ServiceUnavailableErrorResponse',
+        title: 'Service unavailable error',
+        description: 'Service unavailable - the worker processing this account is not available, try again later',
+        fields: {
+            code: Joi.string().example('WorkerNotAvailable').description('Machine-readable error code')
+        }
+    })
+};
+
+// Builds the value for the plugins['hapi-swagger'].responses route option from a list of HTTP
+// error status codes, so that error responses are rendered in Swagger UI in addition to the
+// 200 response that hapi-swagger picks up from the route's response.schema option. This is
+// documentation only and does not affect request processing in any way.
+function errorResponses(...statusCodes) {
+    let responses = {};
+    for (let statusCode of statusCodes) {
+        if (!errorResponseSchemas[statusCode]) {
+            throw new Error(`Missing error response schema for HTTP status code ${statusCode}`);
+        }
+        responses[statusCode] = errorResponseSchemas[statusCode];
+    }
+    return responses;
+}
+
 module.exports = {
     ADDRESS_STRATEGIES,
+    ACCOUNT_DISPLAY_STATES,
 
     settingsSchema,
     accountSchemas,
@@ -2104,6 +2442,7 @@ module.exports = {
     messageEntrySchema,
     messageDetailsSchema,
     messageListSchema,
+    documentStoreQuerySchema,
     mailboxesSchema,
     shortMailboxesSchema,
     licenseSchema,
@@ -2117,11 +2456,16 @@ module.exports = {
     tokenRestrictionsSchema,
     accountIdSchema,
     ipSchema,
+    tokenIdSchema,
     accountCountersSchema,
     accountPathSchema,
     messageSpecialUseSchema,
     defaultAccountTypeSchema,
     fromAddressSchema,
+    responseAddressSchema,
+    responseFromAddressSchema,
+    emailIdSchema,
+    threadIdSchema,
     outboxEntrySchema,
     googleProjectIdSchema,
     googleTopicNameSchema,
@@ -2135,7 +2479,8 @@ module.exports = {
     exportListSchema,
     exportProgressSchema,
     exportIdSchema,
-    pubSubErrorSchema
+    pubSubErrorSchema,
+    errorResponses
 };
 
 /*