emailengine-app 2.69.0 → 2.70.0

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

@@ -11,7 +11,7 @@ const util = require('util');
 
 const LOG_VERBOSE = getBoolean(process.env.EE_OPENAPI_VERBOSE);
 
-const { accountIdSchema, addressSchema, messageSpecialUseSchema, fromAddressSchema } = require('../schemas');
+const { accountIdSchema, messageSpecialUseSchema, responseAddressSchema, responseFromAddressSchema, errorResponses } = require('../schemas');
 
 function getDateValue(str) {
     try {
@@ -97,7 +97,7 @@ async function init(args) {
             startTime: sortingResponse?.start_time,
             endTime: sortingResponse?.end_time,
             model: sortingResponse?.model,
-            tokens: sortingResponse.tokens
+            tokens: sortingResponse?.tokens
         });
 
         // Step 2. Embeddings for the request
@@ -195,7 +195,7 @@ async function init(args) {
                 filter: vectorsFilter?.bool?.must
             });
             return {
-                success: true,
+                success: false,
                 answer: null,
                 processPipeline
             };
@@ -281,7 +281,7 @@ async function init(args) {
             message: 'Retrieved the answer',
             messages: queryResponse?.messageId?.length || 0,
             model: queryResponse?.model,
-            tokens: queryResponse.tokens
+            tokens: queryResponse?.tokens
         });
 
         if (queryResponse?.answer) {
@@ -360,7 +360,7 @@ async function init(args) {
         }
 
         return {
-            success: !!(responseData.answer || responseData.message),
+            success: !!responseData.answer,
             ...responseData,
             processPipeline
         };
@@ -399,9 +399,13 @@ async function init(args) {
         options: {
             description: 'Chat with emails',
             notes: 'Use OpenAI API and embeddings stored in the Document Store to "chat" with account emails. Requires Document Store indexing and the "Chat with emails" feature to be enabled.',
-            tags: ['Deprecated endpoints (Document Store)'],
+            tags: ['api', 'Deprecated endpoints (Document Store)'],
 
-            plugins: {},
+            plugins: {
+                'hapi-swagger': {
+                    responses: errorResponses(400, 401, 403, 404, 429, 500)
+                }
+            },
 
             auth: {
                 strategy: 'api-token',
@@ -434,30 +438,44 @@ async function init(args) {
 
             response: {
                 schema: Joi.object({
-                    success: Joi.boolean().example(true).description('Was the request successful').label('ReturnChatResponseSuccess'),
-                    answer: Joi.string().trim().example('Last tuesday').description('Chat response').label('ChatResponse').required(),
+                    success: Joi.boolean()
+                        .example(true)
+                        .description('Whether the LLM produced an answer. Can be false on a 200 response when no answer was found')
+                        .label('ReturnChatResponseSuccess'),
+                    answer: Joi.string()
+                        .trim()
+                        .allow(null)
+                        .example('Last tuesday')
+                        .description('Chat response. Not present (or null) when no answer was produced')
+                        .label('ChatResponse'),
                     messages: Joi.array()
                         .items(
                             Joi.object({
                                 id: Joi.string().example('AAAAAgAACrI').description('Unique identifier for the message').label('ChatMessageId'),
                                 path: Joi.string().example('INBOX').description('Folder this message was found from').label('ChatMessagePath'),
                                 date: Joi.date().iso().example('2023-09-29T10:03:49.000Z').description('Date of the email'),
-                                from: fromAddressSchema,
+                                from: responseFromAddressSchema,
 
                                 to: Joi.array()
-                                    .items(addressSchema)
+                                    .items(responseAddressSchema)
                                     .single()
                                     .description('List of addresses')
                                     .example([{ address: 'recipient@example.com' }])
-                                    .label('AddressList'),
-                                subject: Joi.string().allow('').example('What a wonderful message').description('Message subject'),
+                                    .label('ChatToAddressList'),
+                                cc: Joi.array().items(responseAddressSchema).single().description('List of CC addresses').label('ChatCcAddressList'),
+                                bcc: Joi.array().items(responseAddressSchema).single().description('List of BCC addresses').label('ChatBccAddressList'),
+                                subject: Joi.string().example('What a wonderful message').description('Message subject'),
                                 messageSpecialUse: messageSpecialUseSchema
                             })
                                 .description('Email that best matched the question')
                                 .label('ChatResponseMessage')
                         )
                         .description('Emails that best matched the question')
-                        .label('ChatResponseMessages')
+                        .label('ChatResponseMessages'),
+                    processPipeline: Joi.array()
+                        .items(Joi.object().unknown().label('ChatProcessPipelineStep'))
+                        .description('Diagnostic information about the chat processing steps, including timings and token usage')
+                        .label('ChatProcessPipeline')
                 }).label('ReturnChatResponse'),
                 failAction: 'log'
             }

package/lib/api-routes/delivery-test-routes.js

@@ -8,7 +8,7 @@ const { Account } = require('../account');
 const { Gateway } = require('../gateway');
 const getSecret = require('../get-secret');
 const { failAction, httpAgent } = require('../tools');
-const { accountIdSchema } = require('../schemas');
+const { accountIdSchema, errorResponses } = require('../schemas');
 const { REDIS_PREFIX } = require('../consts');
 const packageData = require('../../package.json');
 
@@ -137,6 +137,12 @@ ${now}`,
             notes: 'Initiate a delivery test',
             tags: ['api', 'Delivery Test'],
 
+            plugins: {
+                'hapi-swagger': {
+                    responses: errorResponses(400, 401, 403, 404, 429, 500)
+                }
+            },
+
             auth: {
                 strategy: 'api-token',
                 mode: 'required'
@@ -162,13 +168,20 @@ ${now}`,
 
             response: {
                 schema: Joi.object({
-                    success: Joi.boolean().example(true).description('Was the test started').label('ResponseDeliveryStartSuccess'),
+                    success: Joi.boolean()
+                        .example(true)
+                        .description('Was the test started. Not present if queueing the test message failed')
+                        .label('ResponseDeliveryStartSuccess'),
                     deliveryTest: Joi.string()
                         .guid({
                             version: ['uuidv4', 'uuidv5']
                         })
                         .example('6420a6ad-7f82-4e4f-8112-82a9dad1f34d')
-                        .description('Test ID')
+                        .description('Test ID. Not present if queueing the test message failed'),
+                    error: Joi.string()
+                        .example('Oops, something went wrong')
+                        .description('Error message. Only present if queueing the test message failed - in that case success and deliveryTest are not set')
+                        .label('ResponseDeliveryStartError')
                 }).label('DeliveryStartResponse'),
                 failAction: 'log'
             }
@@ -242,7 +255,7 @@ ${now}`,
                     };
 
                     if (testResponse.spf && testResponse.spf.status && testResponse.spf.status.comment) {
-                        testResponse.spf.status.comment = testResponse.spf.status.comment.replace(/^[^:\s]+:s*/, '');
+                        testResponse.spf.status.comment = testResponse.spf.status.comment.replace(/^[^:\s]+:\s*/, '');
                     }
                 }
 
@@ -274,6 +287,12 @@ ${now}`,
             notes: 'Check delivery test status',
             tags: ['api', 'Delivery Test'],
 
+            plugins: {
+                'hapi-swagger': {
+                    responses: errorResponses(400, 401, 403, 404, 429, 500)
+                }
+            },
+
             auth: {
                 strategy: 'api-token',
                 mode: 'required'
@@ -302,6 +321,10 @@ ${now}`,
             response: {
                 schema: Joi.object({
                     success: Joi.boolean().example(true).description('Was the test completed').label('ResponseDeliveryCheckSuccess'),
+                    status: Joi.string()
+                        .example('pending')
+                        .description('Test status. Only present while the test message has not yet been received (success=false)')
+                        .label('ResponseDeliveryCheckStatus'),
                     dkim: Joi.object().unknown().description('DKIM results').label('DkimResults'),
                     spf: Joi.object().unknown().description('SPF results').label('SpfResults'),
                     dmarc: Joi.object().unknown().description('DMARC results').label('DmarcResults'),
@@ -311,7 +334,9 @@ ${now}`,
                         .unknown()
                         .description('Primary DKIM signature. `status.aligned` should be set, otherwise DKIM check should not be considered as passed.')
                         .label('MainSignature')
-                }).label('DeliveryCheckResponse'),
+                })
+                    .unknown()
+                    .label('DeliveryCheckResponse'),
                 failAction: 'log'
             }
         }

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

@@ -5,7 +5,7 @@ const { Export } = require('../export');
 const Boom = require('@hapi/boom');
 const Joi = require('joi');
 const { failAction } = require('../tools');
-const { accountIdSchema, exportRequestSchema, exportStatusSchema, exportListSchema, exportIdSchema } = require('../schemas');
+const { accountIdSchema, exportRequestSchema, exportStatusSchema, exportListSchema, exportIdSchema, errorResponses } = require('../schemas');
 const getSecret = require('../get-secret');
 const { createDecryptStream } = require('../stream-encrypt');
 const { handleError } = require('./route-helpers');
@@ -37,6 +37,12 @@ async function init(args) {
             notes: 'Creates a new bulk message export job. The export runs asynchronously and notifies via webhook when complete.',
             tags: ['api', 'Export (Beta)'],
 
+            plugins: {
+                'hapi-swagger': {
+                    responses: errorResponses(400, 401, 403, 404, 429, 500)
+                }
+            },
+
             auth: {
                 strategy: 'api-token',
                 mode: 'required'
@@ -90,6 +96,12 @@ async function init(args) {
             notes: 'Returns the status and progress of an export job.',
             tags: ['api', 'Export (Beta)'],
 
+            plugins: {
+                'hapi-swagger': {
+                    responses: errorResponses(400, 401, 403, 404, 429, 500)
+                }
+            },
+
             auth: {
                 strategy: 'api-token',
                 mode: 'required'
@@ -167,7 +179,8 @@ async function init(args) {
 
             plugins: {
                 'hapi-swagger': {
-                    produces: ['application/gzip']
+                    produces: ['application/gzip'],
+                    responses: errorResponses(400, 401, 403, 404, 429, 500, 503)
                 }
             },
 
@@ -214,6 +227,12 @@ async function init(args) {
             notes: 'Cancels a pending export or deletes a completed export. Removes both Redis data and the export file.',
             tags: ['api', 'Export (Beta)'],
 
+            plugins: {
+                'hapi-swagger': {
+                    responses: errorResponses(400, 401, 403, 404, 429, 500)
+                }
+            },
+
             auth: {
                 strategy: 'api-token',
                 mode: 'required'
@@ -263,6 +282,12 @@ async function init(args) {
             notes: 'Lists all exports for an account with pagination.',
             tags: ['api', 'Export (Beta)'],
 
+            plugins: {
+                'hapi-swagger': {
+                    responses: errorResponses(400, 401, 403, 429, 500)
+                }
+            },
+
             auth: {
                 strategy: 'api-token',
                 mode: 'required'

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

@@ -6,7 +6,23 @@ const { Gateway } = require('../gateway');
 const getSecret = require('../get-secret');
 const { failAction } = require('../tools');
 const { handleError } = require('./route-helpers');
-const { lastErrorSchema } = require('../schemas');
+const { errorResponses } = require('../schemas');
+
+// Gateways store SMTP delivery errors, not OAuth2 errors, so the error shape differs from the
+// account-level lastErrorSchema
+const gatewayLastErrorSchema = Joi.object({
+    created: Joi.number().integer().example(1623868624153).description('Timestamp of the error as milliseconds from epoch'),
+    status: Joi.string().valid('error').example('error').description('Status of the last delivery attempt'),
+    response: Joi.string().example('535 Authentication failed').description('SMTP server response for the failed delivery'),
+    responseCode: Joi.number().integer().example(535).description('SMTP response code'),
+    code: Joi.string().example('EAUTH').description('Error type identifier'),
+    command: Joi.string().example('AUTH PLAIN').description('SMTP command that failed'),
+    description: Joi.string().example('Authentication failed').description('Error description'),
+    networkRouting: Joi.object().unknown().allow(null).description('Network routing information for the delivery attempt').label('GatewayErrorNetworkRouting')
+})
+    .unknown()
+    .description('Information about the last failed delivery attempt using this gateway')
+    .label('GatewayErrorEntry');
 
 async function init(args) {
     const { server, call, CORS_CONFIG } = args;
@@ -30,7 +46,11 @@ async function init(args) {
             notes: 'Lists registered gateways',
             tags: ['api', 'SMTP Gateway'],
 
-            plugins: {},
+            plugins: {
+                'hapi-swagger': {
+                    responses: errorResponses(400, 401, 403, 429, 500)
+                }
+            },
 
             auth: {
                 strategy: 'api-token',
@@ -71,8 +91,12 @@ async function init(args) {
                                 gateway: Joi.string().max(256).required().example('example').description('Gateway ID'),
                                 name: Joi.string().max(256).example('My Email Gateway').description('Display name for the gateway'),
                                 deliveries: Joi.number().integer().empty('').example(100).description('Count of email deliveries using this gateway'),
-                                lastUse: Joi.date().iso().example('2021-02-17T13:43:18.860Z').description('Last delivery time'),
-                                lastError: lastErrorSchema.allow(null)
+                                lastUse: Joi.date()
+                                    .iso()
+                                    .allow(null)
+                                    .example('2021-02-17T13:43:18.860Z')
+                                    .description('Last delivery time. Null for gateways that have not been used yet'),
+                                lastError: gatewayLastErrorSchema.allow(null)
                             }).label('GatewayResponseItem')
                         )
                         .label('GatewayEntries')
@@ -114,6 +138,12 @@ async function init(args) {
             notes: 'Returns stored information about the gateway. Passwords are not included.',
             tags: ['api', 'SMTP Gateway'],
 
+            plugins: {
+                'hapi-swagger': {
+                    responses: errorResponses(400, 401, 403, 404, 429, 500)
+                }
+            },
+
             auth: {
                 strategy: 'api-token',
                 mode: 'required'
@@ -139,10 +169,18 @@ async function init(args) {
 
                     name: Joi.string().max(256).required().example('My Email Gateway').description('Display name for the gateway'),
                     deliveries: Joi.number().integer().empty('').example(100).description('Count of email deliveries using this gateway'),
-                    lastUse: Joi.date().iso().example('2021-02-17T13:43:18.860Z').description('Last delivery time'),
-
-                    user: Joi.string().empty('').trim().max(1024).description('SMTP authentication username').label('UserName'),
-                    pass: Joi.string().empty('').max(1024).description('SMTP authentication password').label('Password'),
+                    lastUse: Joi.date()
+                        .iso()
+                        .allow(null)
+                        .example('2021-02-17T13:43:18.860Z')
+                        .description('Last delivery time. Null for gateways that have not been used yet'),
+
+                    user: Joi.string().empty('').trim().allow(null).max(1024).description('SMTP authentication username').label('UserName'),
+                    pass: Joi.string()
+                        .empty('')
+                        .max(1024)
+                        .description('SMTP authentication password. Always returned as the masked value "******" when a password is set')
+                        .label('Password'),
 
                     host: Joi.string().hostname().example('smtp.gmail.com').description('Hostname to connect to').label('Hostname'),
                     port: Joi.number()
@@ -156,12 +194,13 @@ async function init(args) {
                     secure: Joi.boolean()
                         .truthy('Y', 'true', '1', 'on')
                         .falsy('N', 'false', 0, '')
+                        .allow(null)
                         .default(false)
                         .example(true)
                         .description('Should connection use TLS. Usually true for port 465')
                         .label('GatewayTlsOptions'),
 
-                    lastError: lastErrorSchema.allow(null)
+                    lastError: gatewayLastErrorSchema.allow(null)
                 }).label('GatewayResponse'),
                 failAction: 'log'
             }
@@ -188,7 +227,11 @@ async function init(args) {
             notes: 'Registers a new SMP gateway',
             tags: ['api', 'SMTP Gateway'],
 
-            plugins: {},
+            plugins: {
+                'hapi-swagger': {
+                    responses: errorResponses(400, 401, 403, 429, 500)
+                }
+            },
 
             auth: {
                 strategy: 'api-token',
@@ -265,7 +308,11 @@ async function init(args) {
             notes: 'Updates gateway information',
             tags: ['api', 'SMTP Gateway'],
 
-            plugins: {},
+            plugins: {
+                'hapi-swagger': {
+                    responses: errorResponses(400, 401, 403, 404, 429, 500)
+                }
+            },
 
             auth: {
                 strategy: 'api-token',
@@ -341,7 +388,11 @@ async function init(args) {
             notes: 'Delete SMTP gateway data',
             tags: ['api', 'SMTP Gateway'],
 
-            plugins: {},
+            plugins: {
+                'hapi-swagger': {
+                    responses: errorResponses(400, 401, 403, 404, 429, 500)
+                }
+            },
 
             auth: {
                 strategy: 'api-token',

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

@@ -3,7 +3,7 @@
 const Joi = require('joi');
 const { failAction } = require('../tools');
 const { handleError } = require('./route-helpers');
-const { licenseSchema } = require('../schemas');
+const { licenseSchema, errorResponses } = require('../schemas');
 
 async function init(args) {
     const { server, call, CORS_CONFIG } = args;
@@ -30,6 +30,12 @@ async function init(args) {
             notes: 'Get active license information',
             tags: ['api', 'License'],
 
+            plugins: {
+                'hapi-swagger': {
+                    responses: errorResponses(401, 403, 429, 500)
+                }
+            },
+
             auth: {
                 strategy: 'api-token',
                 mode: 'required'
@@ -65,7 +71,11 @@ async function init(args) {
             notes: 'Remove registered active license',
             tags: ['api', 'License'],
 
-            plugins: {},
+            plugins: {
+                'hapi-swagger': {
+                    responses: errorResponses(401, 403, 429, 500)
+                }
+            },
 
             auth: {
                 strategy: 'api-token',
@@ -77,7 +87,7 @@ async function init(args) {
                 schema: Joi.object({
                     active: Joi.boolean().example(false),
                     details: Joi.boolean().example(false),
-                    type: Joi.string().example('SSPL-1.0-or-later')
+                    type: Joi.string().example('LICENSE_EMAILENGINE')
                 }).label('EmptyLicenseResponse'),
                 failAction: 'log'
             }
@@ -106,7 +116,11 @@ async function init(args) {
             notes: 'Set up a license for EmailEngine to unlock all features',
             tags: ['api', 'License'],
 
-            plugins: {},
+            plugins: {
+                'hapi-swagger': {
+                    responses: errorResponses(400, 401, 403, 429, 500)
+                }
+            },
 
             auth: {
                 strategy: 'api-token',

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

@@ -7,7 +7,7 @@ const { Account } = require('../account');
 const getSecret = require('../get-secret');
 const { failAction } = require('../tools');
 const { handleError } = require('./route-helpers');
-const { accountIdSchema, mailboxesSchema } = require('../schemas');
+const { accountIdSchema, mailboxesSchema, errorResponses } = require('../schemas');
 
 async function init(args) {
     const { server, call, CORS_CONFIG, FLAG_SORT_ORDER } = args;
@@ -55,6 +55,12 @@ async function init(args) {
             notes: 'Lists all available mailboxes',
             tags: ['api', 'Mailbox'],
 
+            plugins: {
+                'hapi-swagger': {
+                    responses: errorResponses(400, 401, 403, 404, 429, 500, 503)
+                }
+            },
+
             auth: {
                 strategy: 'api-token',
                 mode: 'required'
@@ -128,7 +134,11 @@ async function init(args) {
             notes: 'Create new mailbox folder',
             tags: ['api', 'Mailbox'],
 
-            plugins: {},
+            plugins: {
+                'hapi-swagger': {
+                    responses: errorResponses(400, 401, 403, 404, 429, 500, 503)
+                }
+            },
 
             auth: {
                 strategy: 'api-token',
@@ -154,13 +164,13 @@ async function init(args) {
                         .single()
                         .example(['Parent folder', 'Subfolder'])
                         .description('Mailbox path as an array or a string. If account is namespaced then namespace prefix is added by default.')
-                        .label('MailboxPath')
+                        .label('CreateMailboxPathInput')
                 }).label('CreateMailbox')
             },
 
             response: {
                 schema: Joi.object({
-                    path: Joi.string().required().example('Kalender/S&APw-nnip&AOQ-evad').description('Full path to mailbox').label('MailboxPath'),
+                    path: Joi.string().required().example('Kalender/S&APw-nnip&AOQ-evad').description('Full path to mailbox').label('CreatedMailboxPath'),
                     mailboxId: Joi.string().example('1439876283476').description('Mailbox ID (if server has support)').label('MailboxId'),
                     created: Joi.boolean().example(true).description('Was the mailbox created')
                 }).label('CreateMailboxResponse'),
@@ -205,7 +215,11 @@ async function init(args) {
             notes: 'Modify an existing mailbox folder (rename or change subscription status)',
             tags: ['api', 'Mailbox'],
 
-            plugins: {},
+            plugins: {
+                'hapi-swagger': {
+                    responses: errorResponses(400, 401, 403, 404, 429, 500, 503)
+                }
+            },
 
             auth: {
                 strategy: 'api-token',
@@ -244,8 +258,12 @@ async function init(args) {
 
             response: {
                 schema: Joi.object({
-                    path: Joi.string().required().example('Mail').description('Mailbox folder path').label('ExistingMailboxPath'),
+                    path: Joi.string().example('Mail').description('Mailbox folder path').label('ExistingMailboxPath'),
                     newPath: Joi.string().example('Kalender/S&APw-nnip&AOQ-evad').description('Full path to mailbox if renamed').label('NewMailboxPath'),
+                    mailboxId: Joi.string()
+                        .example('1439876283476')
+                        .description('Mailbox ID after the rename (Gmail API and MS Graph API accounts only)')
+                        .label('ModifyMailboxId'),
                     renamed: Joi.boolean().example(true).description('Was the mailbox renamed'),
                     subscribed: Joi.boolean().example(true).description('Subscription status after modification')
                 }).label('ModifyMailboxResponse'),
@@ -279,7 +297,11 @@ async function init(args) {
             notes: 'Delete existing mailbox folder',
             tags: ['api', 'Mailbox'],
 
-            plugins: {},
+            plugins: {
+                'hapi-swagger': {
+                    responses: errorResponses(400, 401, 403, 404, 429, 500, 503)
+                }
+            },
 
             auth: {
                 strategy: 'api-token',
@@ -307,6 +329,10 @@ async function init(args) {
             response: {
                 schema: Joi.object({
                     path: Joi.string().required().example('Kalender/S&APw-nnip&AOQ-evad').description('Full path to mailbox').label('MailboxPath'),
+                    mailboxId: Joi.string()
+                        .example('1439876283476')
+                        .description('ID of the deleted mailbox (Gmail API and MS Graph API accounts only)')
+                        .label('DeleteMailboxId'),
                     deleted: Joi.boolean().example(true).description('Was the mailbox deleted')
                 }).label('DeleteMailboxResponse'),
                 failAction: 'log'