emailengine-app 2.69.0 → 2.70.0

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

@@ -12,17 +12,39 @@ const {
     accountIdSchema,
     messageDetailsSchema,
     messageListSchema,
+    messageEntrySchema,
     documentStoreSchema,
+    documentStoreQuerySchema,
     searchSchema,
     messageUpdateSchema,
     addressSchema,
     fromAddressSchema,
-    messageReferenceSchema
+    messageReferenceSchema,
+    emailIdSchema,
+    threadIdSchema,
+    errorResponses
 } = require('../schemas');
 
 const listMessageFolderPathDescription =
     'Mailbox folder path. Can use special use labels like "\\Sent". Special value "\\All" is available for Gmail IMAP, Gmail API, MS Graph API accounts.';
 
+// Response field for a flag or label update operation. IMAP accounts return a boolean (whether
+// the operation succeeded), API-based accounts echo the requested values as an array.
+const updateOpResultSchema = (op, noun, entryLabel, example, label) =>
+    Joi.alternatives()
+        .try(Joi.boolean(), Joi.array().items(Joi.string().label(entryLabel)))
+        .example(example)
+        .description(`Did the ${op} operation succeed (boolean, IMAP accounts) or the requested ${noun} (array, API-based accounts)`)
+        .label(label);
+
+// Source-to-target ID map for messages that were moved to another folder. Only the IMAP backend
+// provides this info.
+const idMapSchema = Joi.array()
+    .items(Joi.array().length(2).items(Joi.string().max(256).required().description('Message ID')).label('IdMapTuple'))
+    .example([['AAAAAQAACnA', 'AAAAAwAAAD4']])
+    .description('An optional map of source and target ID values, if the server provided this info (IMAP accounts only)')
+    .label('IdMapArray');
+
 async function init(args) {
     const { server, call, CORS_CONFIG, MAX_ATTACHMENT_SIZE, MAX_BODY_SIZE, MAX_PAYLOAD_TIMEOUT } = args;
 
@@ -60,7 +82,8 @@ async function init(args) {
 
             plugins: {
                 'hapi-swagger': {
-                    produces: ['message/rfc822']
+                    produces: ['message/rfc822'],
+                    responses: errorResponses(400, 401, 403, 404, 429, 500, 503)
                 }
             },
 
@@ -106,6 +129,12 @@ async function init(args) {
             notes: 'Returns details of a specific message. By default text content is not included, use textType value to force retrieving text',
             tags: ['api', 'Message'],
 
+            plugins: {
+                'hapi-swagger': {
+                    responses: errorResponses(400, 401, 403, 404, 429, 500, 503)
+                }
+            },
+
             auth: {
                 strategy: 'api-token',
                 mode: 'required'
@@ -210,7 +239,11 @@ async function init(args) {
             notes: 'Upload a message structure, compile it into an EML file and store it into selected mailbox.',
             tags: ['api', 'Message'],
 
-            plugins: {},
+            plugins: {
+                'hapi-swagger': {
+                    responses: errorResponses(400, 401, 403, 404, 429, 500, 503)
+                }
+            },
 
             auth: {
                 strategy: 'api-token',
@@ -324,9 +357,11 @@ async function init(args) {
                         )
                         .label('MessageAppendId'),
                     path: Joi.string().example('INBOX').description('Folder this message was uploaded to').label('MessageAppendPath'),
-                    uid: Joi.number().integer().example(12345).description('UID of uploaded message'),
-                    uidValidity: Joi.string().example('12345').description('UIDVALIDITY of the target folder. Numeric value cast as string.'),
-                    seq: Joi.number().integer().example(12345).description('Sequence number of uploaded message'),
+                    uid: Joi.number().integer().example(12345).description('UID of uploaded message (IMAP accounts only)'),
+                    uidValidity: Joi.string()
+                        .example('12345')
+                        .description('UIDVALIDITY of the target folder. Numeric value cast as string. IMAP accounts only.'),
+                    seq: Joi.number().integer().example(12345).description('Sequence number of uploaded message (IMAP accounts only)'),
 
                     messageId: Joi.string().max(996).example('<test123@example.com>').description('Message ID'),
 
@@ -334,9 +369,9 @@ async function init(args) {
                         message: Joi.string()
                             .base64({ paddingRequired: false, urlSafe: true })
                             .max(256)
-                            .required()
                             .example('AAAAAQAACnA')
-                            .description('Referenced message ID'),
+                            .description('Referenced message ID. Not present when only a thread ID was referenced'),
+                        threadId: threadIdSchema.description('Referenced thread ID (Gmail API accounts only)').label('ResponseReferenceThreadId'),
                         success: Joi.boolean().example(true).description('Was the referenced message processed').label('ResponseReferenceSuccess'),
                         documentStore: documentStoreSchema.default(false),
                         error: Joi.string().example('Referenced message was not found').description('An error message if referenced message processing failed')
@@ -374,7 +409,11 @@ async function init(args) {
             notes: 'Update message information. Mainly this means changing message flag values',
             tags: ['api', 'Message'],
 
-            plugins: {},
+            plugins: {
+                'hapi-swagger': {
+                    responses: errorResponses(400, 401, 403, 404, 429, 500, 503)
+                }
+            },
 
             auth: {
                 strategy: 'api-token',
@@ -400,14 +439,24 @@ async function init(args) {
             response: {
                 schema: Joi.object({
                     flags: Joi.object({
-                        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')
+                        add: updateOpResultSchema('add', 'flags', 'FlagEntry', true, 'FlagAddResult'),
+                        delete: updateOpResultSchema('delete', 'flags', 'FlagEntry', false, 'FlagDeleteResult'),
+                        set: updateOpResultSchema('set', 'flags', 'FlagEntry', true, 'FlagSetResult'),
+                        result: Joi.array()
+                            .items(Joi.string().label('FlagEntry'))
+                            .example(['\\Seen'])
+                            .description('Resulting flag set after the update (Gmail API and MS Graph API accounts only)')
+                            .label('FlagResultList')
                     }).label('FlagUpdateResponse'),
                     labels: Joi.object({
-                        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')
+                        add: updateOpResultSchema('add', 'labels', 'LabelEntry', ['Label1', 'Label2'], 'LabelAddResult'),
+                        delete: updateOpResultSchema('delete', 'labels', 'LabelEntry', ['Label3'], 'LabelDeleteResult'),
+                        set: updateOpResultSchema('set', 'labels', 'LabelEntry', ['Label1'], 'LabelSetResult'),
+                        result: Joi.array()
+                            .items(Joi.string().label('LabelEntry'))
+                            .example(['Label1'])
+                            .description('Resulting label set after the update (Gmail API and MS Graph API accounts only)')
+                            .label('LabelResultList')
                     }).label('LabelUpdateResponse')
                 }).label('MessageUpdateResponse'),
                 failAction: 'log'
@@ -440,7 +489,11 @@ async function init(args) {
             notes: 'Update message information for matching emails',
             tags: ['api', 'Multi Message Actions'],
 
-            plugins: {},
+            plugins: {
+                'hapi-swagger': {
+                    responses: errorResponses(400, 401, 403, 404, 429, 500, 503)
+                }
+            },
 
             auth: {
                 strategy: 'api-token',
@@ -472,15 +525,19 @@ async function init(args) {
             response: {
                 schema: Joi.object({
                     flags: Joi.object({
-                        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')
+                        add: updateOpResultSchema('add', 'flags', 'BulkFlagEntry', true, 'BulkFlagAddResult'),
+                        delete: updateOpResultSchema('delete', 'flags', 'BulkFlagEntry', false, 'BulkFlagDeleteResult'),
+                        set: updateOpResultSchema('set', 'flags', 'BulkFlagEntry', true, 'BulkFlagSetResult')
                     }).label('BulkFlagUpdateResponse'),
                     labels: Joi.object({
-                        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')
+                        add: updateOpResultSchema('add', 'labels', 'BulkLabelEntry', ['Label1', 'Label2'], 'BulkLabelAddResult'),
+                        delete: updateOpResultSchema('delete', 'labels', 'BulkLabelEntry', ['Label3'], 'BulkLabelDeleteResult'),
+                        set: updateOpResultSchema('set', 'labels', 'BulkLabelEntry', ['Label1'], 'BulkLabelSetResult')
+                    }).label('BulkLabelUpdateResponse'),
+                    emailIds: Joi.array()
+                        .items(emailIdSchema)
+                        .description('List of updated email IDs (Gmail API and MS Graph API accounts only)')
+                        .label('BulkUpdatedEmailIds')
                 }).label('BulkMessageUpdateResponse'),
                 failAction: 'log'
             }
@@ -516,7 +573,11 @@ async function init(args) {
             notes: 'Moves a message to a target folder',
             tags: ['api', 'Message'],
 
-            plugins: {},
+            plugins: {
+                'hapi-swagger': {
+                    responses: errorResponses(400, 401, 403, 404, 429, 500, 503)
+                }
+            },
 
             auth: {
                 strategy: 'api-token',
@@ -586,7 +647,11 @@ async function init(args) {
             notes: 'Move messages matching to a search query to another folder',
             tags: ['api', 'Multi Message Actions'],
 
-            plugins: {},
+            plugins: {
+                'hapi-swagger': {
+                    responses: errorResponses(400, 401, 403, 404, 429, 500, 503)
+                }
+            },
 
             auth: {
                 strategy: 'api-token',
@@ -620,16 +685,15 @@ async function init(args) {
                 schema: Joi.object({
                     path: Joi.string().required().example('INBOX').description('Target mailbox folder path'),
 
-                    idMap: Joi.array()
-                        .items(Joi.array().length(2).items(Joi.string().max(256).required().description('Message ID')).label('IdMapTuple'))
-                        .example([['AAAAAQAACnA', 'AAAAAwAAAD4']])
-                        .description('An optional map of source and target ID values, if the server provided this info')
-                        .label('IdMapArray'),
+                    idMap: idMapSchema,
 
                     emailIds: Joi.array()
-                        .items(Joi.string().example('1278455344230334865'))
-                        .description('An optional list of emailId values, if the server supports unique email IDs')
-                        .label('EmailIdsArray')
+                        .items(emailIdSchema)
+                        .allow(null)
+                        .description(
+                            'An optional list of emailId values, if the server supports unique email IDs (Gmail API and MS Graph API accounts only). Null when no messages matched the search (Gmail API)'
+                        )
+                        .label('MovedEmailIdsArray')
                 }).label('MessagesMoveResponse'),
                 failAction: 'log'
             }
@@ -661,7 +725,11 @@ async function init(args) {
             notes: 'Move message to Trash or delete it if already in Trash',
             tags: ['api', 'Message'],
 
-            plugins: {},
+            plugins: {
+                'hapi-swagger': {
+                    responses: errorResponses(400, 401, 403, 404, 429, 500, 503)
+                }
+            },
 
             auth: {
                 strategy: 'api-token',
@@ -693,10 +761,20 @@ async function init(args) {
             },
             response: {
                 schema: Joi.object({
-                    deleted: Joi.boolean().example(false).description('Was the delete action executed'),
+                    deleted: Joi.boolean()
+                        .example(false)
+                        .description(
+                            'Was the message deleted permanently. IMAP accounts return false when the message was moved to Trash, Gmail API and MS Graph API accounts return true also for moves to Trash'
+                        ),
                     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')
+                        destination: Joi.string()
+                            .example('Trash')
+                            .description('Trash folder path. Can be missing if the server did not provide the destination folder')
+                            .label('TrashPath'),
+                        message: Joi.string()
+                            .example('AAAAAwAAAWg')
+                            .description('Message ID in Trash. Can be missing if the server did not provide the new message ID')
+                            .label('TrashMessageId')
                     })
                         .description('Present if message was moved to Trash')
                         .label('MessageMovedToTrash')
@@ -731,7 +809,11 @@ async function init(args) {
             notes: 'Move messages to Trash or delete these if already in Trash',
             tags: ['api', 'Multi Message Actions'],
 
-            plugins: {},
+            plugins: {
+                'hapi-swagger': {
+                    responses: errorResponses(400, 401, 403, 404, 429, 500, 503)
+                }
+            },
 
             auth: {
                 strategy: 'api-token',
@@ -757,7 +839,7 @@ async function init(args) {
                         .truthy('Y', 'true', '1')
                         .falsy('N', 'false', 0)
                         .default(false)
-                        .description('Delete messages even if not in Trash')
+                        .description('Delete messages even if not in Trash. Not supported for Gmail API accounts (messages are always moved to Trash)')
                         .label('ForceDelete')
                 }).label('MessagesDeleteQuery'),
 
@@ -768,23 +850,33 @@ async function init(args) {
 
             response: {
                 schema: Joi.object({
-                    deleted: Joi.boolean().example(false).description('Was the delete action executed'),
+                    deleted: Joi.boolean()
+                        .example(false)
+                        .description(
+                            'Was the delete action executed. IMAP accounts return false when messages were moved to Trash, Gmail API and MS Graph API accounts return true also for moves to Trash'
+                        ),
                     moved: Joi.object({
                         destination: Joi.string().required().example('Trash').description('Trash folder path').label('TrashPath'),
 
-                        idMap: Joi.array()
-                            .items(Joi.array().length(2).items(Joi.string().max(256).required().description('Message ID')).label('IdMapTuple'))
-                            .example([['AAAAAQAACnA', 'AAAAAwAAAD4']])
-                            .description('An optional map of source and target ID values, if the server provided this info')
-                            .label('IdMapArray'),
+                        idMap: idMapSchema,
 
                         emailIds: Joi.array()
-                            .items(Joi.string().example('1278455344230334865'))
-                            .description('An optional list of emailId values, if the server supports unique email IDs')
-                            .label('EmailIdsArray')
+                            .items(emailIdSchema)
+                            .description(
+                                'An optional list of emailId values, if the server supports unique email IDs (Gmail API and MS Graph API accounts only)'
+                            )
+                            .label('TrashedEmailIdsArray')
                     })
                         .label('MessagesMovedToTrash')
-                        .description('Value is present if messages were moved to Trash')
+                        .description('Value is present if messages were moved to Trash'),
+                    deletedMessages: Joi.object({
+                        emailIds: Joi.array()
+                            .items(emailIdSchema)
+                            .description('List of emailId values of the permanently deleted messages')
+                            .label('DeletedEmailIdsArray')
+                    })
+                        .label('MessagesDeleted')
+                        .description('Value is present if messages were deleted permanently (MS Graph API accounts only)')
                 }).label('MessagesDeleteResponse'),
                 failAction: 'log'
             }
@@ -817,6 +909,12 @@ async function init(args) {
             notes: 'Lists messages in a mailbox folder',
             tags: ['api', 'Message'],
 
+            plugins: {
+                'hapi-swagger': {
+                    responses: errorResponses(400, 401, 403, 404, 429, 500, 503)
+                }
+            },
+
             auth: {
                 strategy: 'api-token',
                 mode: 'required'
@@ -916,7 +1014,11 @@ async function init(args) {
             notes: 'Filter messages from a mailbox folder by search options. Search is performed against a specific folder and not for the entire account.',
             tags: ['api', 'Message'],
 
-            plugins: {},
+            plugins: {
+                'hapi-swagger': {
+                    responses: errorResponses(400, 401, 403, 404, 422, 429, 500, 503)
+                }
+            },
 
             auth: {
                 strategy: 'api-token',
@@ -980,7 +1082,7 @@ async function init(args) {
                     exposeQuery: Joi.boolean()
                         .truthy('Y', 'true', '1')
                         .falsy('N', 'false', 0)
-                        .description('If enabled then returns the ElasticSearch query for debugging as part of the response')
+                        .description('If enabled then includes the combined query (as the documentStoreQuery field) in the response for debugging')
                         .label('exposeQuery')
                         .when('documentStore', {
                             is: true,
@@ -1074,9 +1176,13 @@ async function init(args) {
         options: {
             description: 'Unified search for messages',
             notes: 'Filter messages from the Document Store for multiple accounts or paths. Document Store must be enabled for the unified search to work.',
-            tags: ['Deprecated endpoints (Document Store)'],
+            tags: ['api', 'Deprecated endpoints (Document Store)'],
 
-            plugins: {},
+            plugins: {
+                'hapi-swagger': {
+                    responses: errorResponses(400, 401, 403, 429, 500)
+                }
+            },
 
             auth: {
                 strategy: 'api-token',
@@ -1104,7 +1210,7 @@ async function init(args) {
                     exposeQuery: Joi.boolean()
                         .truthy('Y', 'true', '1')
                         .falsy('N', 'false', 0)
-                        .description('If enabled then returns the ElasticSearch query for debugging as part of the response')
+                        .description('If enabled then includes the combined query (as the documentStoreQuery field) in the response for debugging')
                         .label('exposeQuery')
                         .optional()
                         .meta({ swaggerHidden: true })
@@ -1127,7 +1233,34 @@ async function init(args) {
             },
 
             response: {
-                schema: messageListSchema,
+                schema: Joi.object({
+                    total: Joi.number()
+                        .integer()
+                        .example(120)
+                        .description('Total number of matching messages (capped at 10000 by the Document Store)')
+                        .label('UnifiedTotalNumber'),
+                    page: Joi.number().integer().example(0).description('Current page number (zero-based)').label('UnifiedPageNumber'),
+                    pages: Joi.number().integer().example(24).description('Total number of pages available').label('UnifiedPagesNumber'),
+                    accounts: Joi.array()
+                        .items(Joi.string().example('example'))
+                        .description('Account filter used for the search, if provided')
+                        .label('UnifiedSearchAccountsEcho'),
+                    paths: Joi.array()
+                        .items(Joi.string().example('INBOX'))
+                        .description('Path filter used for the search, if provided')
+                        .label('UnifiedSearchPathsEcho'),
+                    messages: Joi.array()
+                        .items(
+                            messageEntrySchema
+                                .keys({
+                                    account: accountIdSchema.description('Account ID this message belongs to')
+                                })
+                                .unknown()
+                                .label('UnifiedMessageListEntry')
+                        )
+                        .label('UnifiedPageMessages'),
+                    documentStoreQuery: documentStoreQuerySchema
+                }).label('UnifiedSearchResponse'),
                 failAction: 'log'
             }
         }
@@ -1159,6 +1292,12 @@ async function init(args) {
             notes: 'Retrieves message text',
             tags: ['api', 'Message'],
 
+            plugins: {
+                'hapi-swagger': {
+                    responses: errorResponses(400, 401, 403, 404, 429, 500, 503)
+                }
+            },
+
             auth: {
                 strategy: 'api-token',
                 mode: 'required'
@@ -1179,7 +1318,7 @@ async function init(args) {
                         .min(0)
                         .max(1024 * 1024 * 1024)
                         .example(MAX_ATTACHMENT_SIZE)
-                        .description('Max length of text content'),
+                        .description('Max length of text content. Ignored for Gmail API and MS Graph API accounts (full content is always returned)'),
                     textType: Joi.string()
                         .lowercase()
                         .valid('html', 'plain', '*')
@@ -1205,7 +1344,9 @@ async function init(args) {
                 schema: Joi.object({
                     plain: Joi.string().example('Hello world').description('Plaintext content'),
                     html: Joi.string().example('<p>Hello world</p>').description('HTML content'),
-                    hasMore: Joi.boolean().example(false).description('Is the current text output capped or not')
+                    hasMore: Joi.boolean()
+                        .example(false)
+                        .description('Is the current text output capped or not. Always false for Gmail API and MS Graph API accounts')
                 }).label('TextResponse'),
                 failAction: 'log'
             }
@@ -1245,7 +1386,8 @@ async function init(args) {
 
             plugins: {
                 'hapi-swagger': {
-                    produces: ['application/octet-stream']
+                    produces: ['application/octet-stream'],
+                    responses: errorResponses(400, 401, 403, 404, 429, 500, 503)
                 }
             },