emailengine-app 2.61.4 → 2.62.0

package/lib/api-routes/message-routes.js

@@ -147,7 +147,8 @@ async function init(args) {
                         .lowercase()
                         .valid('html', 'plain', '*')
                         .example('*')
-                        .description('Which text content to return, use * for all. By default text content is not returned.'),
+                        .description('Which text content to return, use * for all. By default text content is not returned.')
+                        .label('MessageTextType'),
 
                     webSafeHtml: Joi.boolean()
                         .truthy('Y', 'true', '1')
@@ -310,9 +311,9 @@ async function init(args) {
                                     }),
 
                                 contentType: Joi.string().lowercase().max(256).example('image/gif'),
-                                contentDisposition: Joi.string().lowercase().valid('inline', 'attachment'),
+                                contentDisposition: Joi.string().lowercase().valid('inline', 'attachment').label('MsgUploadContentDisposition'),
                                 cid: Joi.string().max(256).example('unique-image-id@localhost').description('Content-ID value for embedded images'),
-                                encoding: Joi.string().valid('base64').default('base64'),
+                                encoding: Joi.string().valid('base64').default('base64').label('MsgUploadEncoding'),
 
                                 reference: Joi.string()
                                     .base64({ paddingRequired: false, urlSafe: true })
@@ -322,6 +323,7 @@ async function init(args) {
                                     .description(
                                         'References an existing attachment by its ID instead of providing new attachment content. If this field is set, the `content` field must not be included. If not set, the `content` field is required.'
                                     )
+                                    .label('MsgUploadReference')
                             }).label('UploadAttachment')
                         )
                         .description('List of attachments')
@@ -430,15 +432,15 @@ async function init(args) {
             response: {
                 schema: Joi.object({
                     flags: Joi.object({
-                        add: Joi.array().items(Joi.string()).example(['\\Seen', '\\Flagged']),
-                        delete: Joi.array().items(Joi.string()).example(['\\Draft']),
-                        set: Joi.array().items(Joi.string()).example(['\\Seen'])
-                    }).label('FlagResponse'),
+                        add: Joi.array().items(Joi.string().label('FlagEntry')).example(['\\Seen', '\\Flagged']).label('FlagAddList'),
+                        delete: Joi.array().items(Joi.string().label('FlagEntry')).example(['\\Draft']).label('FlagDeleteList'),
+                        set: Joi.array().items(Joi.string().label('FlagEntry')).example(['\\Seen']).label('FlagSetList')
+                    }).label('FlagUpdateResponse'),
                     labels: Joi.object({
-                        add: Joi.array().items(Joi.string()).example(['Label1', 'Label2']),
-                        delete: Joi.array().items(Joi.string()).example(['Label3']),
-                        set: Joi.array().items(Joi.string()).example(['Label1'])
-                    }).label('FlagResponse')
+                        add: Joi.array().items(Joi.string().label('LabelEntry')).example(['Label1', 'Label2']).label('LabelAddList'),
+                        delete: Joi.array().items(Joi.string().label('LabelEntry')).example(['Label3']).label('LabelDeleteList'),
+                        set: Joi.array().items(Joi.string().label('LabelEntry')).example(['Label1']).label('LabelSetList')
+                    }).label('LabelUpdateResponse')
                 }).label('MessageUpdateResponse'),
                 failAction: 'log'
             }
@@ -510,16 +512,16 @@ async function init(args) {
             response: {
                 schema: Joi.object({
                     flags: Joi.object({
-                        add: Joi.array().items(Joi.string()).example(['\\Seen', '\\Flagged']),
-                        delete: Joi.array().items(Joi.string()).example(['\\Draft']),
-                        set: Joi.array().items(Joi.string()).example(['\\Seen'])
-                    }).label('FlagResponse'),
+                        add: Joi.array().items(Joi.string().label('BulkFlagEntry')).example(['\\Seen', '\\Flagged']).label('BulkFlagAddList'),
+                        delete: Joi.array().items(Joi.string().label('BulkFlagEntry')).example(['\\Draft']).label('BulkFlagDeleteList'),
+                        set: Joi.array().items(Joi.string().label('BulkFlagEntry')).example(['\\Seen']).label('BulkFlagSetList')
+                    }).label('BulkFlagUpdateResponse'),
                     labels: Joi.object({
-                        add: Joi.array().items(Joi.string()).example(['Label1', 'Label2']),
-                        delete: Joi.array().items(Joi.string()).example(['Label3']),
-                        set: Joi.array().items(Joi.string()).example(['Label1'])
-                    }).label('FlagResponse')
-                }).label('MessageUpdateResponse'),
+                        add: Joi.array().items(Joi.string().label('BulkLabelEntry')).example(['Label1', 'Label2']).label('BulkLabelAddList'),
+                        delete: Joi.array().items(Joi.string().label('BulkLabelEntry')).example(['Label3']).label('BulkLabelDeleteList'),
+                        set: Joi.array().items(Joi.string().label('BulkLabelEntry')).example(['Label1']).label('BulkLabelSetList')
+                    }).label('BulkLabelUpdateResponse')
+                }).label('BulkMessageUpdateResponse'),
                 failAction: 'log'
             }
         }
@@ -759,7 +761,9 @@ async function init(args) {
                     moved: Joi.object({
                         destination: Joi.string().required().example('Trash').description('Trash folder path').label('TrashPath'),
                         message: Joi.string().required().example('AAAAAwAAAWg').description('Message ID in Trash').label('TrashMessageId')
-                    }).description('Present if message was moved to Trash')
+                    })
+                        .description('Present if message was moved to Trash')
+                        .label('MessageMovedToTrash')
                 }).label('MessageDeleteResponse'),
                 failAction: 'log'
             }
@@ -1083,7 +1087,7 @@ async function init(args) {
                         .unknown()
                         .meta({ swaggerHidden: true })
                 })
-                    .label('SearchQuery')
+                    .label('MessageSearchPayload')
                     .example({
                         search: {
                             unseen: true,
@@ -1281,7 +1285,8 @@ async function init(args) {
                         .valid('html', 'plain', '*')
                         .default('*')
                         .example('*')
-                        .description('Which text content to return, use * for all. By default all contents are returned.'),
+                        .description('Which text content to return, use * for all. By default all contents are returned.')
+                        .label('TextSearchTextType'),
                     documentStore: documentStoreSchema.default(false)
                 }),
 

package/lib/api-routes/template-routes.js

@@ -93,7 +93,11 @@ async function init(args) {
                         .example('Something about the template')
                         .description('Optional description of the template')
                         .label('TemplateDescription'),
-                    format: Joi.string().valid('html', 'markdown').default('html').description('Markup language for HTML ("html" or "markdown")'),
+                    format: Joi.string()
+                        .valid('html', 'markdown')
+                        .default('html')
+                        .description('Markup language for HTML ("html" or "markdown")')
+                        .label('TemplateFormat'),
                     content: Joi.object({
                         subject: templateSchemas.subject,
                         text: templateSchemas.text,
@@ -176,7 +180,12 @@ async function init(args) {
                         .example('Something about the template')
                         .description('Optional description of the template')
                         .label('TemplateDescription'),
-                    format: Joi.string().empty('').valid('html', 'markdown').default('html').description('Markup language for HTML ("html" or "markdown")'),
+                    format: Joi.string()
+                        .empty('')
+                        .valid('html', 'markdown')
+                        .default('html')
+                        .description('Markup language for HTML ("html" or "markdown")')
+                        .label('TemplateUpdateFormat'),
                     content: Joi.object({
                         subject: templateSchemas.subject,
                         text: templateSchemas.text,
@@ -277,7 +286,11 @@ async function init(args) {
                                     .example('Something about the template')
                                     .description('Optional description of the template')
                                     .label('TemplateDescription'),
-                                format: Joi.string().valid('html', 'markdown').default('html').description('Markup language for HTML ("html" or "markdown")'),
+                                format: Joi.string()
+                                    .valid('html', 'markdown')
+                                    .default('html')
+                                    .description('Markup language for HTML ("html" or "markdown")')
+                                    .label('TemplateListFormat'),
                                 created: Joi.date().iso().example('2021-02-17T13:43:18.860Z').description('The time this template was created'),
                                 updated: Joi.date().iso().example('2021-02-17T13:43:18.860Z').description('The time this template was last updated')
                             }).label('AccountTemplate')
@@ -345,7 +358,11 @@ async function init(args) {
                         .example('Something about the template')
                         .description('Optional description of the template')
                         .label('TemplateDescription'),
-                    format: Joi.string().valid('html', 'markdown').default('html').description('Markup language for HTML ("html" or "markdown")'),
+                    format: Joi.string()
+                        .valid('html', 'markdown')
+                        .default('html')
+                        .description('Markup language for HTML ("html" or "markdown")')
+                        .label('TemplateResponseFormat'),
                     created: Joi.date().iso().example('2021-02-17T13:43:18.860Z').description('The time this template was created'),
                     updated: Joi.date().iso().example('2021-02-17T13:43:18.860Z').description('The time this template was last updated'),
                     content: Joi.object({
@@ -353,7 +370,11 @@ async function init(args) {
                         text: templateSchemas.text,
                         html: templateSchemas.html,
                         previewText: templateSchemas.previewText,
-                        format: Joi.string().valid('html', 'markdown').default('html').description('Markup language for HTML ("html" or "markdown")')
+                        format: Joi.string()
+                            .valid('html', 'markdown')
+                            .default('html')
+                            .description('Markup language for HTML ("html" or "markdown")')
+                            .label('TemplateContentFormat')
                     }).label('RequestTemplateContent')
                 }).label('AccountTemplateResponse'),
                 failAction: 'log'
@@ -411,7 +432,7 @@ async function init(args) {
                     deleted: Joi.boolean().truthy('Y', 'true', '1').falsy('N', 'false', 0).default(true).description('Was the template deleted'),
                     account: accountIdSchema.required(),
                     id: Joi.string().max(256).required().example('AAABgS-UcAYAAAABAA').description('Template ID')
-                }).label('DeleteTemplateRequestResponse'),
+                }).label('DeleteTemplateResponse'),
                 failAction: 'log'
             }
         }
@@ -480,7 +501,7 @@ async function init(args) {
                 schema: Joi.object({
                     deleted: Joi.boolean().truthy('Y', 'true', '1').falsy('N', 'false', 0).default(true).description('Were the templates flushed'),
                     account: accountIdSchema.required()
-                }).label('DeleteTemplateRequestResponse'),
+                }).label('FlushTemplatesResponse'),
                 failAction: 'log'
             }
         }

package/lib/arf-detect.js

@@ -27,7 +27,7 @@ const arfDetect = async messageInfo => {
 
     let returnPath;
 
-    for (let attachment of messageInfo.attachments) {
+    for (let attachment of messageInfo.attachments || []) {
         switch (attachment.contentType.toLowerCase()) {
             case 'message/feedback-report': {
                 // found a feedback report

package/lib/consts.js

@@ -87,6 +87,22 @@ module.exports = {
     LIST_SUBSCRIBE_NOTIFY: 'listSubscribe',
     LIST_SUBSCRIBE_DESCRIPTION: 'Recipient Subscribed - A recipient re-subscribed to a list',
 
+    EXPORT_COMPLETED_NOTIFY: 'exportCompleted',
+    EXPORT_COMPLETED_DESCRIPTION: 'Export Completed - A bulk message export has completed successfully',
+
+    EXPORT_FAILED_NOTIFY: 'exportFailed',
+    EXPORT_FAILED_DESCRIPTION: 'Export Failed - A bulk message export has failed',
+
+    // Export defaults
+    DEFAULT_EXPORT_MAX_AGE: 24 * 60 * 60 * 1000, // 24 hours
+    DEFAULT_EXPORT_MAX_SIZE: 10 * 1024 * 1024 * 1024, // 10GB
+    DEFAULT_EXPORT_MAX_MESSAGES: 500000,
+    DEFAULT_EXPORT_MAX_CONCURRENT: 2,
+    DEFAULT_EXPORT_MAX_GLOBAL_CONCURRENT: 8,
+    DEFAULT_EXPORT_MAX_MESSAGE_SIZE: 50 * 1024 * 1024, // 50MB
+    DEFAULT_GMAIL_EXPORT_BATCH_SIZE: 10,
+    DEFAULT_OUTLOOK_EXPORT_BATCH_SIZE: 20,
+
     MAX_DAYS_STATS: 7,
 
     DEFAULT_MAX_LOG_LINES: 10000,

package/lib/db.js

@@ -107,12 +107,14 @@ const reqisQueue = new Redis(REDIS_CONF);
 
 module.exports.queueConf = {
     connection: reqisQueue,
+    sharedConnection: true, // Prevent BullMQ from closing shared connection
     prefix: `${REDIS_PREFIX}bull`
 };
 
 const notifyQueue = new Queue('notify', module.exports.queueConf);
 const submitQueue = new Queue('submit', module.exports.queueConf);
 const documentsQueue = new Queue('documents', module.exports.queueConf);
+const exportQueue = new Queue('export', module.exports.queueConf);
 
 const zExpungeScript = fs.readFileSync(pathlib.join(__dirname, '/lua/z-expunge.lua'), 'utf-8');
 const zSetScript = fs.readFileSync(pathlib.join(__dirname, 'lua/z-set.lua'), 'utf-8');
@@ -215,6 +217,7 @@ module.exports.redis = redis;
 module.exports.notifyQueue = notifyQueue;
 module.exports.submitQueue = submitQueue;
 module.exports.documentsQueue = documentsQueue;
+module.exports.exportQueue = exportQueue;
 
 // do not set up the flow producer by default
 module.exports.getFlowProducer = () => new FlowProducer(module.exports.queueConf /*, Redis*/);

package/lib/email-client/base-client.js

@@ -1984,7 +1984,7 @@ class BaseClient {
         // Store message in Redis
         await this.redis.hsetBuffer(`${REDIS_PREFIX}iaq:${this.account}`, queueId, msgEntry);
 
-        let queueKeep = (await settings.get('queueKeep')) || true;
+        let queueKeep = (await settings.get('queueKeep')) ?? true;
 
         // Configure delivery retry settings
         let defaultDeliveryAttempts = await settings.get('deliveryAttempts');
@@ -2007,14 +2007,16 @@ class BaseClient {
 
         // Configure queue job options
         let queueName = 'queued';
+        let retention = typeof queueKeep === 'number' ? { age: 24 * 3600, count: queueKeep } : queueKeep;
         let jobOpts = {
             jobId: queueId,
-            removeOnComplete: queueKeep,
-            removeOnFail: queueKeep,
+            removeOnComplete: retention,
+            removeOnFail: retention,
             attempts: typeof deliveryAttempts === 'number' ? deliveryAttempts : defaultDeliveryAttempts,
             backoff: {
                 type: 'exponential',
-                delay: 5000
+                delay: 5000,
+                jitter: 0.2 // 20% randomization to prevent thundering herd
             }
         };
 

package/lib/email-client/gmail-client.js

@@ -11,6 +11,7 @@ const he = require('he');
 const { BaseClient, metricsMeta } = require('./base-client');
 const { mimeHtml } = require('@postalsys/email-text-tools');
 const { emitChangeEvent } = require('../tools');
+const crypto = require('crypto');
 const { Gateway } = require('../gateway');
 
 const {
@@ -20,11 +21,16 @@ const {
     EMAIL_SENT_NOTIFY,
     REDIS_PREFIX,
     AUTH_ERROR_NOTIFY,
-    AUTH_SUCCESS_NOTIFY
+    AUTH_SUCCESS_NOTIFY,
+    DEFAULT_GMAIL_EXPORT_BATCH_SIZE
 } = require('../consts');
 
+const settings = require('../settings');
+
 const { GMAIL_API_BASE, LIST_BATCH_SIZE, request: gmailApiRequest } = require('./gmail/gmail-api');
 
+const MAX_GMAIL_BATCH_SIZE = 50;
+
 // Labels to exclude from folder listings
 const SKIP_LABELS = ['UNREAD', 'STARRED', 'IMPORTANT', 'CHAT', 'CATEGORY_PERSONAL'];
 
@@ -602,23 +608,39 @@ class GmailClient extends BaseClient {
 
                 return folderData;
             })
-            .filter(value => value)
-            .sort((a, b) => {
-                // Sort: INBOX first, then special folders, then alphabetical
-                if (a.path === 'INBOX') {
-                    return -1;
-                } else if (b.path === 'INBOX') {
-                    return 1;
-                }
+            .filter(value => value);
+
+        // Add virtual "All Mail" folder for Gmail API
+        // This allows exporting all messages without scanning individual labels
+        mailboxes.unshift({
+            id: 'virtual_all',
+            path: '\\All',
+            delimiter: '/',
+            parentPath: '',
+            name: 'All Mail',
+            listed: true,
+            subscribed: false,
+            noSelect: true,
+            specialUse: '\\All',
+            specialUseSource: 'extension'
+        });
 
-                if (a.specialUse && !b.specialUse) {
-                    return -1;
-                } else if (!a.specialUse && b.specialUse) {
-                    return 1;
-                }
+        mailboxes.sort((a, b) => {
+            // Sort: INBOX first, then special folders, then alphabetical
+            if (a.path === 'INBOX') {
+                return -1;
+            } else if (b.path === 'INBOX') {
+                return 1;
+            }
 
-                return a.path.toLowerCase().localeCompare(b.path.toLowerCase());
-            });
+            if (a.specialUse && !b.specialUse) {
+                return -1;
+            } else if (!a.specialUse && b.specialUse) {
+                return 1;
+            }
+
+            return a.path.toLowerCase().localeCompare(b.path.toLowerCase());
+        });
 
         return mailboxes;
     }
@@ -756,7 +778,7 @@ class GmailClient extends BaseClient {
         let nextPageCursor = pageCursor.nextPageCursor(listingResult.nextPageToken);
         let prevPageCursor = pageCursor.prevPageCursor();
 
-        if (options.metadataOnly) {
+        if (options.metadataOnly || query.metadataOnly) {
             // Return just IDs without fetching full content
             return {
                 total: messageCount,
@@ -769,6 +791,8 @@ class GmailClient extends BaseClient {
         }
 
         // Fetch message content for matching messages in batches
+        // Use format=minimal for minimalFields option (faster, returns only id, threadId, labelIds, internalDate, sizeEstimate)
+        const messageFormat = options.minimalFields ? 'minimal' : undefined;
 
         let promises = [];
 
@@ -782,14 +806,16 @@ class GmailClient extends BaseClient {
                     throw entry.reason;
                 }
                 if (entry.value) {
-                    messageList.push(this.formatMessage(entry.value, { path }));
+                    messageList.push(this.formatMessage(entry.value, { path, minimalFields: options.minimalFields }));
                 }
             }
             promises = [];
         };
 
         for (let { id: message } of listingResult.messages || []) {
-            promises.push(this.request(`${GMAIL_API_BASE}/gmail/v1/users/me/messages/${message}`));
+            let requestUrl = `${GMAIL_API_BASE}/gmail/v1/users/me/messages/${message}`;
+            let requestParams = messageFormat ? { format: messageFormat } : undefined;
+            promises.push(this.request(requestUrl, 'get', requestParams));
             if (promises.length > LIST_BATCH_SIZE) {
                 await resolvePromises();
             }
@@ -1269,6 +1295,9 @@ class GmailClient extends BaseClient {
 
         let formattedMessage = this.formatMessage(messageData, { extended: true, textType: options.textType });
 
+        // Resolve label IDs to human-readable names
+        await this.resolveLabels(formattedMessage);
+
         // Mark as seen if requested
         if (options.markAsSeen && (!formattedMessage.flags || !formattedMessage.flags.includes('\\Seen'))) {
             //
@@ -1325,6 +1354,64 @@ class GmailClient extends BaseClient {
         return formattedMessage;
     }
 
+    /**
+     * Fetches multiple messages in parallel for batch export operations
+     * @param {string[]} emailIds - Array of message IDs
+     * @param {Object} options - Fetch options
+     * @returns {Object[]} Array of results with messageId, data, and error fields
+     */
+    async getMessages(emailIds, options) {
+        options = options || {};
+        await this.prepare();
+
+        // Pre-fetch labels to resolve label IDs to names
+        const labelMap = new Map();
+        try {
+            const labelsResult = await this.getLabels();
+            for (const label of labelsResult || []) {
+                labelMap.set(label.id, label.name);
+            }
+        } catch (err) {
+            this.logger.warn({ msg: 'Failed to fetch labels for export, using raw label IDs', account: this.account, err });
+        }
+
+        const results = [];
+        const settingsBatchSize = await settings.get('gmailExportBatchSize');
+        const batchSize = Math.min(settingsBatchSize || DEFAULT_GMAIL_EXPORT_BATCH_SIZE, MAX_GMAIL_BATCH_SIZE);
+
+        for (let i = 0; i < emailIds.length; i += batchSize) {
+            const batch = emailIds.slice(i, i + batchSize);
+
+            const batchResults = await Promise.all(
+                batch.map(async emailId => {
+                    try {
+                        const requestQuery = { format: 'full' };
+                        const messageData = await this.request(`${GMAIL_API_BASE}/gmail/v1/users/me/messages/${emailId}`, 'get', requestQuery);
+                        const formattedMessage = this.formatMessage(messageData, { extended: true, textType: options.textType });
+
+                        await this.resolveLabels(formattedMessage, labelMap);
+
+                        return {
+                            messageId: emailId,
+                            data: formattedMessage,
+                            error: null
+                        };
+                    } catch (err) {
+                        return {
+                            messageId: emailId,
+                            data: null,
+                            error: { message: err.message, code: err.code, statusCode: err.statusCode }
+                        };
+                    }
+                })
+            );
+
+            results.push(...batchResults);
+        }
+
+        return results;
+    }
+
     /**
      * Fetches text content for a message
      * @param {string} textId - Encoded text identifier
@@ -1521,19 +1608,45 @@ class GmailClient extends BaseClient {
             return false;
         }
 
-        // Prepare for Gmail API send
-        let contentType = 'message/rfc822';
-        let payload = raw;
-        let targetEndpoint = `/upload/gmail/v1/users/me/messages/send`;
+        // Gmail JSON endpoint: 5MB body limit (~3.5MB raw before base64url overhead)
+        // Gmail upload endpoint: 35MB raw RFC822
+        let contentType;
+        let payload;
+        let targetEndpoint;
+        const JSON_SEND_LIMIT = 3.5 * 1024 * 1024;
 
-        // Use different endpoint for thread replies
-        if (data?.reference?.threadId) {
-            targetEndpoint = `/gmail/v1/users/me/messages/send`;
+        if (raw.length <= JSON_SEND_LIMIT) {
+            // JSON endpoint with base64url encoding (retry-safe, no ArrayBuffer issues)
             contentType = 'application/json';
-            payload = {
-                raw: raw.toString('base64'),
-                threadId: data?.reference?.threadId
-            };
+            payload = { raw: raw.toString('base64url') };
+            targetEndpoint = `/gmail/v1/users/me/messages/send`;
+            if (data?.reference?.threadId) {
+                payload.threadId = data.reference.threadId;
+            }
+        } else if (data?.reference?.threadId) {
+            // Large threaded reply: multipart upload preserves explicit threadId
+            // via JSON metadata alongside the raw RFC822 message body
+            const boundary = `ee_${crypto.randomBytes(16).toString('hex')}`;
+            const metadata = JSON.stringify({ threadId: data.reference.threadId });
+            const preamble = Buffer.from(
+                `--${boundary}\r\n` +
+                    `Content-Type: application/json; charset=UTF-8\r\n` +
+                    `\r\n` +
+                    `${metadata}\r\n` +
+                    `--${boundary}\r\n` +
+                    `Content-Type: message/rfc822\r\n` +
+                    `\r\n`
+            );
+            const epilogue = Buffer.from(`\r\n--${boundary}--`);
+
+            contentType = `multipart/related; boundary=${boundary}`;
+            payload = Buffer.concat([preamble, raw, epilogue]);
+            targetEndpoint = `/upload/gmail/v1/users/me/messages/send?uploadType=multipart`;
+        } else {
+            // Large non-threaded message: simple upload with raw RFC822 Buffer
+            contentType = 'message/rfc822';
+            payload = raw;
+            targetEndpoint = `/upload/gmail/v1/users/me/messages/send`;
         }
 
         // Send via Gmail API
@@ -1591,7 +1704,8 @@ class GmailClient extends BaseClient {
             await this.redis
                 .multi()
                 .hset(data.feedbackKey, 'success', 'true')
-                .expire(1 * 60 * 60);
+                .expire(data.feedbackKey, 1 * 60 * 60)
+                .exec();
         }
 
         return {
@@ -2042,6 +2156,35 @@ class GmailClient extends BaseClient {
         }
     }
 
+    /**
+     * Resolves label IDs to human-readable names on a formatted message.
+     * Mutates formattedMessage.labels in place. Labels starting with '\\' are
+     * treated as special-use labels and left as-is.
+     *
+     * @param {Object} formattedMessage - Message with a .labels array
+     * @param {Map} [labelMap] - Optional pre-built id-to-name map (avoids an extra getLabels call)
+     */
+    async resolveLabels(formattedMessage, labelMap) {
+        if (!Array.isArray(formattedMessage?.labels)) {
+            return;
+        }
+
+        if (!labelMap) {
+            const labelsResult = await this.getLabels();
+            labelMap = new Map();
+            for (const label of labelsResult || []) {
+                labelMap.set(label.id, label.name);
+            }
+        }
+
+        formattedMessage.labels = formattedMessage.labels.map(label => {
+            if (label.startsWith('\\')) {
+                return label;
+            }
+            return labelMap.get(label) || label;
+        });
+    }
+
     /**
      * Resolves a label by path or ID
      * @param {string} path - Label path or ID
@@ -2292,7 +2435,7 @@ class GmailClient extends BaseClient {
      * @returns {Object} Formatted message
      */
     formatMessage(messageData, options) {
-        let { extended, path, textType } = options || {};
+        let { extended, path, textType, minimalFields } = options || {};
 
         let date = messageData.internalDate && !isNaN(messageData.internalDate) ? new Date(Number(messageData.internalDate)) : undefined;
         if (date?.toString() === 'Invalid Date') {
@@ -2301,6 +2444,34 @@ class GmailClient extends BaseClient {
 
         let { flags, labels, category } = this.formatFlagsAndLabels(messageData);
 
+        // For minimalFields mode (format=minimal), payload is not available
+        // Return only basic fields: id, threadId, labelIds, internalDate, sizeEstimate
+        if (minimalFields) {
+            const result = {
+                id: messageData.id,
+                emailId: messageData.id || undefined,
+                threadId: messageData.threadId || undefined,
+                date: date ? date.toISOString() : undefined,
+                flags,
+                labels,
+                category,
+                unseen: !flags.includes('\\Seen') ? true : undefined,
+                flagged: flags.includes('\\Flagged') ? true : undefined,
+                draft: flags.includes('\\Draft') ? true : undefined,
+                size: messageData.sizeEstimate
+            };
+
+            // Set special-use based on labels
+            for (let specialUseTag of ['\\Junk', '\\Sent', '\\Trash', '\\Inbox', '\\Drafts']) {
+                if (result.labels && result.labels.includes(specialUseTag)) {
+                    result.messageSpecialUse = specialUseTag;
+                    break;
+                }
+            }
+
+            return result;
+        }
+
         let envelope = this.getEnvelope(messageData);
 
         // Extract all headers
@@ -2424,7 +2595,7 @@ class GmailClient extends BaseClient {
      * @returns {string} Formatted term
      */
     formatSearchTerm(term, quot = '"') {
-        if (typeof term === 'object' && term && Object.prototype.toString.apply(new Date()) === '[object Date]') {
+        if (typeof term === 'object' && term && Object.prototype.toString.apply(term) === '[object Date]') {
             term = term.toISOString().substring(0, 10);
         }