emailengine-app 2.68.1 → 2.70.0

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

@@ -4,25 +4,47 @@ const { redis } = require('../db');
 const { Account } = require('../account');
 const getSecret = require('../get-secret');
 const settings = require('../settings');
-const Boom = require('@hapi/boom');
 const Joi = require('joi');
 const { failAction } = require('../tools');
+const { handleError } = require('./route-helpers');
 
 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;
 
@@ -44,15 +66,7 @@ async function init(args) {
                 const response = await accountObject.getRawMessage(request.params.message);
                 return h.response(response);
             } catch (err) {
-                request.logger.error({ msg: 'API request failed', err });
-                if (Boom.isBoom(err)) {
-                    throw err;
-                }
-                let error = Boom.boomify(err, { statusCode: err.statusCode || 500 });
-                if (err.code) {
-                    error.output.payload.code = err.code;
-                }
-                throw error;
+                handleError(request, err);
             }
         },
         options: {
@@ -68,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,15 +121,7 @@ async function init(args) {
             try {
                 return await accountObject.getMessage(request.params.message, request.query);
             } catch (err) {
-                request.logger.error({ msg: 'API request failed', err });
-                if (Boom.isBoom(err)) {
-                    throw err;
-                }
-                let error = Boom.boomify(err, { statusCode: err.statusCode || 500 });
-                if (err.code) {
-                    error.output.payload.code = err.code;
-                }
-                throw error;
+                handleError(request, err);
             }
         },
         options: {
@@ -122,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'
@@ -213,15 +226,7 @@ async function init(args) {
             try {
                 return await accountObject.uploadMessage(request.payload);
             } catch (err) {
-                request.logger.error({ msg: 'API request failed', err });
-                if (Boom.isBoom(err)) {
-                    throw err;
-                }
-                let error = Boom.boomify(err, { statusCode: err.statusCode || 500 });
-                if (err.code) {
-                    error.output.payload.code = err.code;
-                }
-                throw error;
+                handleError(request, err);
             }
         },
         options: {
@@ -234,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',
@@ -348,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'),
 
@@ -358,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')
@@ -390,15 +401,7 @@ async function init(args) {
             try {
                 return await accountObject.updateMessage(request.params.message, request.payload);
             } catch (err) {
-                request.logger.error({ msg: 'API request failed', err });
-                if (Boom.isBoom(err)) {
-                    throw err;
-                }
-                let error = Boom.boomify(err, { statusCode: err.statusCode || 500 });
-                if (err.code) {
-                    error.output.payload.code = err.code;
-                }
-                throw error;
+                handleError(request, err);
             }
         },
         options: {
@@ -406,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',
@@ -432,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'
@@ -464,15 +481,7 @@ async function init(args) {
             try {
                 return await accountObject.updateMessages(request.query.path, request.payload.search, request.payload.update);
             } catch (err) {
-                request.logger.error({ msg: 'API request failed', err });
-                if (Boom.isBoom(err)) {
-                    throw err;
-                }
-                let error = Boom.boomify(err, { statusCode: err.statusCode || 500 });
-                if (err.code) {
-                    error.output.payload.code = err.code;
-                }
-                throw error;
+                handleError(request, err);
             }
         },
         options: {
@@ -480,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',
@@ -512,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'
             }
@@ -548,15 +565,7 @@ async function init(args) {
                 }
                 return await accountObject.moveMessage(request.params.message, { path: request.payload.path }, { source: sourceOption });
             } catch (err) {
-                request.logger.error({ msg: 'API request failed', err });
-                if (Boom.isBoom(err)) {
-                    throw err;
-                }
-                let error = Boom.boomify(err, { statusCode: err.statusCode || 500 });
-                if (err.code) {
-                    error.output.payload.code = err.code;
-                }
-                throw error;
+                handleError(request, err);
             }
         },
         options: {
@@ -564,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',
@@ -626,15 +639,7 @@ async function init(args) {
             try {
                 return await accountObject.moveMessages(request.query.path, request.payload.search, { path: request.payload.path });
             } catch (err) {
-                request.logger.error({ msg: 'API request failed', err });
-                if (Boom.isBoom(err)) {
-                    throw err;
-                }
-                let error = Boom.boomify(err, { statusCode: err.statusCode || 500 });
-                if (err.code) {
-                    error.output.payload.code = err.code;
-                }
-                throw error;
+                handleError(request, err);
             }
         },
         options: {
@@ -642,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',
@@ -676,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'
             }
@@ -709,15 +717,7 @@ async function init(args) {
             try {
                 return await accountObject.deleteMessage(request.params.message, request.query.force);
             } catch (err) {
-                request.logger.error({ msg: 'API request failed', err });
-                if (Boom.isBoom(err)) {
-                    throw err;
-                }
-                let error = Boom.boomify(err, { statusCode: err.statusCode || 500 });
-                if (err.code) {
-                    error.output.payload.code = err.code;
-                }
-                throw error;
+                handleError(request, err);
             }
         },
         options: {
@@ -725,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',
@@ -757,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')
@@ -787,15 +801,7 @@ async function init(args) {
             try {
                 return await accountObject.deleteMessages(request.query.path, request.payload.search, request.query.force);
             } catch (err) {
-                request.logger.error({ msg: 'API request failed', err });
-                if (Boom.isBoom(err)) {
-                    throw err;
-                }
-                let error = Boom.boomify(err, { statusCode: err.statusCode || 500 });
-                if (err.code) {
-                    error.output.payload.code = err.code;
-                }
-                throw error;
+                handleError(request, err);
             }
         },
         options: {
@@ -803,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',
@@ -829,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'),
 
@@ -840,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'
             }
@@ -881,15 +901,7 @@ async function init(args) {
             try {
                 return await accountObject.listMessages(request.query);
             } catch (err) {
-                request.logger.error({ msg: 'API request failed', err });
-                if (Boom.isBoom(err)) {
-                    throw err;
-                }
-                let error = Boom.boomify(err, { statusCode: err.statusCode || 500 });
-                if (err.code) {
-                    error.output.payload.code = err.code;
-                }
-                throw error;
+                handleError(request, err);
             }
         },
         options: {
@@ -897,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'
@@ -988,15 +1006,7 @@ async function init(args) {
             try {
                 return await accountObject.searchMessages(Object.assign(request.query, request.payload));
             } catch (err) {
-                request.logger.error({ msg: 'API request failed', err });
-                if (Boom.isBoom(err)) {
-                    throw err;
-                }
-                let error = Boom.boomify(err, { statusCode: err.statusCode || 500 });
-                if (err.code) {
-                    error.output.payload.code = err.code;
-                }
-                throw error;
+                handleError(request, err);
             }
         },
         options: {
@@ -1004,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',
@@ -1059,7 +1073,7 @@ async function init(args) {
                         .truthy('Y', 'true', '1')
                         .falsy('N', 'false', 0)
                         .description(
-                            'MS Graph only. If enabled, uses the $search parameter for MS Graph search queries instead of $filter. This allows searching the "to", "cc", "bcc", "larger", "smaller", "body", "before", "sentBefore", "since", and the "sentSince" fields. Note that $search returns up to 1,000 results, does not indicate the total number of matching results or pages, and returns results sorted by relevance rather than date.'
+                            'MS Graph only. If enabled, uses the $search parameter for MS Graph search queries instead of $filter. This allows searching the "to", "cc", "bcc", "larger", "smaller", "body", "before", "sentBefore", "since", and the "sentSince" fields. Note that $search returns up to 1,000 results, does not indicate the total number of matching results or pages, and returns results sorted by relevance rather than date. The "labels" filter is not available in this mode - leave this option disabled to filter by category.'
                         )
                         .label('useOutlookSearch')
                         .optional(),
@@ -1068,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,
@@ -1102,7 +1116,11 @@ async function init(args) {
                             header: {
                                 'Message-ID': '<12345@example.com>'
                             },
-                            gmailRaw: 'has:attachment in:unread'
+                            gmailRaw: 'has:attachment in:unread',
+                            labels: {
+                                has: ['Important'],
+                                not: ['Horizon']
+                            }
                         }
                     })
             },
@@ -1152,23 +1170,19 @@ async function init(args) {
             try {
                 return await accountObject.searchMessages(Object.assign({ documentStore: true }, request.query, request.payload), { unified: true });
             } catch (err) {
-                request.logger.error({ msg: 'API request failed', err });
-                if (Boom.isBoom(err)) {
-                    throw err;
-                }
-                let error = Boom.boomify(err, { statusCode: err.statusCode || 500 });
-                if (err.code) {
-                    error.output.payload.code = err.code;
-                }
-                throw error;
+                handleError(request, err);
             }
         },
         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',
@@ -1196,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 })
@@ -1219,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'
             }
         }
@@ -1243,15 +1284,7 @@ async function init(args) {
             try {
                 return await accountObject.getText(request.params.text, request.query);
             } catch (err) {
-                request.logger.error({ msg: 'API request failed', err });
-                if (Boom.isBoom(err)) {
-                    throw err;
-                }
-                let error = Boom.boomify(err, { statusCode: err.statusCode || 500 });
-                if (err.code) {
-                    error.output.payload.code = err.code;
-                }
-                throw error;
+                handleError(request, err);
             }
         },
         options: {
@@ -1259,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'
@@ -1279,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', '*')
@@ -1305,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'
             }
@@ -1329,15 +1370,7 @@ async function init(args) {
             try {
                 return await accountObject.getAttachment(request.params.attachment);
             } catch (err) {
-                request.logger.error({ msg: 'API request failed', err });
-                if (Boom.isBoom(err)) {
-                    throw err;
-                }
-                let error = Boom.boomify(err, { statusCode: err.statusCode || 500 });
-                if (err.code) {
-                    error.output.payload.code = err.code;
-                }
-                throw error;
+                handleError(request, err);
             }
         },
         options: {
@@ -1353,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)
                 }
             },