emailengine-app 2.69.0 → 2.71.0

package/lib/api-routes/oauth2-app-routes.js

@@ -11,13 +11,52 @@ const {
     googleProjectIdSchema,
     googleWorkspaceAccountsSchema,
     googleTopicNameSchema,
-    googleSubscriptionNameSchema
+    googleSubscriptionNameSchema,
+    errorResponses
 } = require('../schemas');
-const { handleError, flattenOAuthAppMeta } = require('./route-helpers');
+const { handleError, throwNotFound, flattenOAuthAppMeta } = require('./route-helpers');
+
+// Stored fields that are returned on OAuth2 application objects in addition to the basic fields
+const oauth2AppExtraFields = {
+    extraScopes: Joi.array()
+        .items(Joi.string().example('https://graph.microsoft.com/.default').label('ExtraScopeEntry'))
+        .description('Additional OAuth2 scopes requested for this app')
+        .label('AppExtraScopes'),
+    skipScopes: Joi.array()
+        .items(Joi.string().example('SMTP.Send').label('SkipScopeEntry'))
+        .description('OAuth2 scopes excluded from the defaults for this app')
+        .label('AppSkipScopes'),
+    baseScopes: oauthCreateSchema.baseScopes.description('OAuth2 base scopes for this app').label('AppBaseScopes'),
+    pubSubApp: oauthCreateSchema.pubSubApp.description('Cloud Pub/Sub app ID used for Gmail change notifications').label('AppPubSubApp'),
+    authMethod: Joi.string().example('serviceKey').description('Authentication method for Gmail service accounts'),
+    cloud: Joi.string().example('global').description('Azure cloud type for Outlook OAuth2 applications'),
+    tenant: Joi.string()
+        .example('f8cdef31-a31e-4b4a-93e4-5f571e91255a')
+        .description('Deprecated and unused directory tenant value. Use the authority field instead'),
+    externalAccount: Joi.string().example('******').description('External account identifier for 2-legged OAuth2 applications. Actual value is not revealed.'),
+    accessToken: Joi.string().example('******').description('Access token for app-based authentication. Actual value is not revealed.'),
+    pubSubTopic: Joi.string().example('projects/project-name/topics/ee-pub-12345').description('Cloud Pub/Sub topic name for Gmail change notifications'),
+    pubSubSubscription: Joi.string()
+        .example('projects/project-name/subscriptions/ee-sub-12345')
+        .description('Cloud Pub/Sub subscription name for Gmail change notifications'),
+    pubSubIamPolicy: Joi.boolean().example(true).description('Whether the IAM policy for the Cloud Pub/Sub topic has been set up')
+};
 
 async function init(args) {
     const { server, call, CORS_CONFIG, OAuth2ProviderSchema } = args;
 
+    // Notify the worker when an app create/update changed Pub/Sub resources, and strip the
+    // internal marker from the API response
+    let applyPubSubUpdates = async result => {
+        if (result && result.pubsubUpdates) {
+            if (Object.keys(result.pubsubUpdates).length > 0) {
+                await call({ cmd: 'googlePubSub', app: result.id });
+            }
+            delete result.pubsubUpdates;
+        }
+        return result;
+    };
+
     server.route({
         method: 'GET',
         path: '/v1/oauth2',
@@ -55,7 +94,11 @@ async function init(args) {
             notes: 'Lists registered OAuth2 applications',
             tags: ['api', 'OAuth2 Applications'],
 
-            plugins: {},
+            plugins: {
+                'hapi-swagger': {
+                    responses: errorResponses(400, 401, 403, 429, 500)
+                }
+            },
 
             auth: {
                 strategy: 'api-token',
@@ -109,7 +152,10 @@ async function init(args) {
                                     .falsy('N', 'false', 0, '')
                                     .example(true)
                                     .description('`true` for older OAuth2 apps set via the settings endpoint'),
-                                created: Joi.date().iso().example('2021-02-17T13:43:18.860Z').description('The time this entry was added').required(),
+                                created: Joi.date()
+                                    .iso()
+                                    .example('2021-02-17T13:43:18.860Z')
+                                    .description('The time this entry was added. Not present for legacy apps'),
                                 updated: Joi.date().iso().example('2021-02-17T13:43:18.860Z').description('The time this entry was updated'),
                                 includeInListing: Joi.boolean()
                                     .truthy('Y', 'true', '1', 'on')
@@ -153,6 +199,8 @@ async function init(args) {
                                     .example('******')
                                     .description('PEM formatted service secret for 2-legged OAuth2 applications. Actual value is not revealed.'),
 
+                                ...oauth2AppExtraFields,
+
                                 lastError: lastErrorSchema.allow(null),
                                 pubSubError: pubSubErrorSchema.allow(null)
                             }).label('OAuth2ResponseItem')
@@ -171,6 +219,9 @@ async function init(args) {
         async handler(request) {
             try {
                 let app = await oauth2Apps.get(request.params.app);
+                if (!app) {
+                    throwNotFound();
+                }
 
                 // remove secrets
                 for (let secretKey of ['clientSecret', 'serviceKey', 'accessToken', 'externalAccount']) {
@@ -199,6 +250,12 @@ async function init(args) {
             notes: 'Returns stored information about an OAuth2 application. Secrets are not included.',
             tags: ['api', 'OAuth2 Applications'],
 
+            plugins: {
+                'hapi-swagger': {
+                    responses: errorResponses(400, 401, 403, 404, 429, 500)
+                }
+            },
+
             auth: {
                 strategy: 'api-token',
                 mode: 'required'
@@ -236,7 +293,7 @@ async function init(args) {
                         .falsy('N', 'false', 0, '')
                         .example(true)
                         .description('`true` for older OAuth2 apps set via the settings endpoint'),
-                    created: Joi.date().iso().example('2021-02-17T13:43:18.860Z').description('The time this entry was added').required(),
+                    created: Joi.date().iso().example('2021-02-17T13:43:18.860Z').description('The time this entry was added. Not present for legacy apps'),
                     updated: Joi.date().iso().example('2021-02-17T13:43:18.860Z').description('The time this entry was updated'),
                     includeInListing: Joi.boolean()
                         .truthy('Y', 'true', '1', 'on')
@@ -283,6 +340,8 @@ async function init(args) {
                         .example(12)
                         .description('The number of accounts registered with this application. Not available for legacy apps.'),
 
+                    ...oauth2AppExtraFields,
+
                     lastError: lastErrorSchema.allow(null),
                     pubSubError: pubSubErrorSchema.allow(null)
                 }).label('ApplicationResponse'),
@@ -298,13 +357,7 @@ async function init(args) {
         async handler(request) {
             try {
                 let result = await oauth2Apps.create(request.payload);
-
-                if (result && result.pubsubUpdates && Object.keys(result.pubsubUpdates).length > 0) {
-                    await call({ cmd: 'googlePubSub', app: result.id });
-                    delete result.pubsubUpdates;
-                }
-
-                return result;
+                return await applyPubSubUpdates(result);
             } catch (err) {
                 handleError(request, err);
             }
@@ -315,7 +368,11 @@ async function init(args) {
             notes: 'Registers a new OAuth2 application for a specific provider',
             tags: ['api', 'OAuth2 Applications'],
 
-            plugins: {},
+            plugins: {
+                'hapi-swagger': {
+                    responses: errorResponses(400, 401, 403, 429, 500)
+                }
+            },
 
             auth: {
                 strategy: 'api-token',
@@ -351,13 +408,7 @@ async function init(args) {
         async handler(request) {
             try {
                 let result = await oauth2Apps.update(request.params.app, request.payload);
-
-                if (result && result.pubsubUpdates && Object.keys(result.pubsubUpdates).length > 0) {
-                    await call({ cmd: 'googlePubSub', app: result.id });
-                    delete result.pubsubUpdates;
-                }
-
-                return result;
+                return await applyPubSubUpdates(result);
             } catch (err) {
                 handleError(request, err);
             }
@@ -367,7 +418,11 @@ async function init(args) {
             notes: 'Updates OAuth2 application information',
             tags: ['api', 'OAuth2 Applications'],
 
-            plugins: {},
+            plugins: {
+                'hapi-swagger': {
+                    responses: errorResponses(400, 401, 403, 404, 429, 500)
+                }
+            },
 
             auth: {
                 strategy: 'api-token',
@@ -481,7 +536,9 @@ async function init(args) {
 
             response: {
                 schema: Joi.object({
-                    id: Joi.string().max(256).required().example('example').description('OAuth2 app ID')
+                    id: Joi.string().max(256).required().example('example').description('OAuth2 app ID'),
+                    updated: Joi.boolean().example(true).description('Was the application updated'),
+                    legacy: Joi.boolean().example(false).description('`true` for older OAuth2 apps set via the settings endpoint')
                 }).label('UpdateOAuthAppResponse'),
                 failAction: 'log'
             }
@@ -512,7 +569,11 @@ async function init(args) {
             notes: 'Delete OAuth2 application data',
             tags: ['api', 'OAuth2 Applications'],
 
-            plugins: {},
+            plugins: {
+                'hapi-swagger': {
+                    responses: errorResponses(400, 401, 403, 404, 429, 500)
+                }
+            },
 
             auth: {
                 strategy: 'api-token',
@@ -537,6 +598,7 @@ async function init(args) {
                 schema: Joi.object({
                     id: Joi.string().max(256).required().example('AAABhaBPHscAAAAH').description('OAuth2 application ID'),
                     deleted: Joi.boolean().truthy('Y', 'true', '1').falsy('N', 'false', 0).default(true).description('Was the OAuth2 application deleted'),
+                    legacy: Joi.boolean().example(false).description('`true` for older OAuth2 apps set via the settings endpoint'),
                     accounts: Joi.number()
                         .integer()
                         .example(12)
@@ -566,7 +628,11 @@ async function init(args) {
             notes: 'Runs the provider authentication chain step by step and reports which steps pass or fail, with hints for fixing failures. For service-account apps an optional mailbox address enables the delegation and live mailbox checks.',
             tags: ['api', 'OAuth2 Applications'],
 
-            plugins: {},
+            plugins: {
+                'hapi-swagger': {
+                    responses: errorResponses(400, 401, 403, 404, 429, 500)
+                }
+            },
 
             auth: {
                 strategy: 'api-token',

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

@@ -6,7 +6,7 @@ const logger = require('../logger');
 const outbox = require('../outbox');
 const { failAction } = require('../tools');
 const { handleError } = require('./route-helpers');
-const { outboxEntrySchema } = require('../schemas');
+const { outboxEntrySchema, errorResponses } = require('../schemas');
 
 async function init(args) {
     const { server, CORS_CONFIG } = args;
@@ -28,7 +28,11 @@ async function init(args) {
             notes: 'Lists messages in the Outbox',
             tags: ['api', 'Outbox'],
 
-            plugins: {},
+            plugins: {
+                'hapi-swagger': {
+                    responses: errorResponses(400, 401, 403, 429, 500)
+                }
+            },
 
             auth: {
                 strategy: 'api-token',
@@ -93,7 +97,11 @@ async function init(args) {
             notes: 'Gets a queued message in the Outbox',
             tags: ['api', 'Outbox'],
 
-            plugins: {},
+            plugins: {
+                'hapi-swagger': {
+                    responses: errorResponses(400, 401, 403, 404, 429, 500)
+                }
+            },
 
             auth: {
                 strategy: 'api-token',
@@ -139,7 +147,11 @@ async function init(args) {
             notes: 'Remove a message from the outbox',
             tags: ['api', 'Outbox'],
 
-            plugins: {},
+            plugins: {
+                'hapi-swagger': {
+                    responses: errorResponses(400, 401, 403, 429, 500)
+                }
+            },
 
             auth: {
                 strategy: 'api-token',

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

@@ -3,7 +3,7 @@
 const Joi = require('joi');
 const { failAction } = require('../tools');
 const { oauth2Apps } = require('../oauth2-apps');
-const { pubSubErrorSchema } = require('../schemas');
+const { pubSubErrorSchema, errorResponses } = require('../schemas');
 const { handleError, flattenOAuthAppMeta } = require('./route-helpers');
 
 async function init(args) {
@@ -38,7 +38,11 @@ async function init(args) {
             notes: 'Lists Pub/Sub enabled OAuth2 applications and their subscription status',
             tags: ['api', 'OAuth2 Applications'],
 
-            plugins: {},
+            plugins: {
+                'hapi-swagger': {
+                    responses: errorResponses(400, 401, 403, 429, 500)
+                }
+            },
 
             auth: {
                 strategy: 'api-token',
@@ -79,10 +83,10 @@ async function init(args) {
                                 id: Joi.string().max(256).required().example('AAABhaBPHscAAAAH').description('OAuth2 application ID'),
                                 name: Joi.string().allow(null).max(256).example('My Gmail App').description('Display name for the app'),
                                 lastError: Joi.object({
-                                    response: Joi.string().example('Enable the Cloud Pub/Sub API').description('Setup error message')
+                                    response: Joi.string().example('Enable the Cloud Pub/Sub API').description('Error message')
                                 })
                                     .allow(null)
-                                    .description('Setup error from ensurePubsub, if any')
+                                    .description('Last Pub/Sub related error for this app - either a setup error or an OAuth2 token renewal failure')
                                     .label('PubSubSetupError'),
                                 pubSubError: pubSubErrorSchema.allow(null)
                             }).label('PubSubAppStatus')

package/lib/api-routes/route-helpers.js

@@ -21,9 +21,22 @@ function handleError(request, err) {
     if (err.code) {
         error.output.payload.code = err.code;
     }
+    if (err.details) {
+        error.output.payload.details = err.details;
+    }
     throw error;
 }
 
+// Throws the canonical 404 error used when an entity getter returns a falsy value. Matches the
+// error shape that the lib-level update() methods (templates, webhooks, oauth2-apps) already throw
+// for missing documents, so API clients see the same error for both code paths.
+function throwNotFound(message = 'Document was not found') {
+    let err = new Error(message);
+    err.code = 'NotFound';
+    err.statusCode = 404;
+    throw err;
+}
+
 // Strips the internal `meta` field from an OAuth2 application object before returning it to the API
 // client, surfacing any authentication or Pub/Sub error messages as `lastError`/`pubSubError`.
 // Pure function: it mutates the passed object and closes over no module state.
@@ -42,4 +55,4 @@ function flattenOAuthAppMeta(app) {
     }
 }
 
-module.exports = { handleError, flattenOAuthAppMeta };
+module.exports = { handleError, throwNotFound, flattenOAuthAppMeta };

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

@@ -7,7 +7,28 @@ const consts = require('../consts');
 const { REDIS_PREFIX } = consts;
 const { failAction } = require('../tools');
 const { handleError } = require('./route-helpers');
-const { settingsSchema, settingsQuerySchema } = require('../schemas');
+const { settingsSchema, settingsQuerySchema, errorResponses } = require('../schemas');
+
+// Response variant of the settings schema. Secret values are masked and returned as booleans,
+// any setting that has never been set is returned as null, and the virtual eventTypes key is
+// not part of the stored settings.
+const settingsOutputSchema = {};
+for (let key of Object.keys(settingsSchema)) {
+    if (settings.encryptedKeys.includes(key)) {
+        settingsOutputSchema[key] = Joi.boolean()
+            .allow(null)
+            .example(true)
+            .description('Whether a value is set for this setting. Secret values are never returned, only a boolean marker');
+    } else {
+        // Use a distinct label for the nullable response variant, otherwise the generated
+        // OpenAPI spec would contain suffixed duplicates of the request-side components
+        settingsOutputSchema[key] = settingsSchema[key].allow(null).label(`${key}Response`);
+    }
+}
+settingsOutputSchema.eventTypes = Joi.array()
+    .items(Joi.string().example('messageNew').label('EventTypeEntry'))
+    .description('Supported webhook event types')
+    .label('EventTypesList');
 
 async function init(args) {
     const { server, notify, CORS_CONFIG } = args;
@@ -22,13 +43,8 @@ async function init(args) {
                 if (request.query[key]) {
                     if (key === 'eventTypes') {
                         values[key] = Object.keys(consts)
-                            .map(key => {
-                                if (/_NOTIFY?/.test(key)) {
-                                    return consts[key];
-                                }
-                                return false;
-                            })
-                            .map(key => key);
+                            .filter(key => /_NOTIFY?/.test(key))
+                            .map(key => consts[key]);
                         continue;
                     }
 
@@ -50,6 +66,12 @@ async function init(args) {
             notes: 'List setting values for specific keys',
             tags: ['api', 'Settings'],
 
+            plugins: {
+                'hapi-swagger': {
+                    responses: errorResponses(400, 401, 403, 429, 500)
+                }
+            },
+
             auth: {
                 strategy: 'api-token',
                 mode: 'required'
@@ -68,7 +90,7 @@ async function init(args) {
             },
 
             response: {
-                schema: Joi.object(settingsSchema).label('SettingsQueryResponse'),
+                schema: Joi.object(settingsOutputSchema).label('SettingsQueryResponse'),
                 failAction: 'log'
             }
         }
@@ -81,19 +103,9 @@ async function init(args) {
         async handler(request) {
             let updated = [];
             for (let key of Object.keys(request.payload)) {
-                switch (key) {
-                    case 'serviceUrl': {
-                        let url = new URL(request.payload.serviceUrl);
-                        request.payload.serviceUrl = url.origin;
-                        break;
-                    }
-
-                    case 'webhooksEnabled':
-                        if (!request.payload.webhooksEnabled) {
-                            // clear error message (if exists)
-                            await settings.clear('webhookErrorFlag');
-                        }
-                        break;
+                if (key === 'webhooksEnabled' && !request.payload.webhooksEnabled) {
+                    // clear error message (if exists)
+                    await settings.clear('webhookErrorFlag');
                 }
 
                 await settings.set(key, request.payload[key]);
@@ -110,7 +122,11 @@ async function init(args) {
             notes: 'Set setting values for specific keys',
             tags: ['api', 'Settings'],
 
-            plugins: {},
+            plugins: {
+                'hapi-swagger': {
+                    responses: errorResponses(400, 401, 403, 429, 500)
+                }
+            },
 
             auth: {
                 strategy: 'api-token',
@@ -160,7 +176,7 @@ async function init(args) {
 
                 if (resActive[0] || resDelayed[0] || resPaused[0] || resWaiting[0]) {
                     // counting failed
-                    let err = new Error('Failed to count queue lengtho');
+                    let err = new Error('Failed to count queue length');
                     err.statusCode = 500;
                     throw err;
                 }
@@ -184,6 +200,12 @@ async function init(args) {
             notes: 'Show queue status and current state',
             tags: ['api', 'Settings'],
 
+            plugins: {
+                'hapi-swagger': {
+                    responses: errorResponses(400, 401, 403, 429, 500)
+                }
+            },
+
             auth: {
                 strategy: 'api-token',
                 mode: 'required'
@@ -278,7 +300,11 @@ async function init(args) {
             notes: 'Set queue settings',
             tags: ['api', 'Settings'],
 
-            plugins: {},
+            plugins: {
+                'hapi-swagger': {
+                    responses: errorResponses(400, 401, 403, 429, 500)
+                }
+            },
 
             auth: {
                 strategy: 'api-token',

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

@@ -4,6 +4,7 @@ const Joi = require('joi');
 const { redis } = require('../db');
 const { failAction, getStats } = require('../tools');
 const { MAX_DAYS_STATS } = require('../consts');
+const { errorResponses } = require('../schemas');
 const packageData = require('../../package.json');
 
 async function init(args) {
@@ -21,6 +22,12 @@ async function init(args) {
             description: 'Return server stats',
             tags: ['api', 'Stats'],
 
+            plugins: {
+                'hapi-swagger': {
+                    responses: errorResponses(400, 401, 403, 429, 500)
+                }
+            },
+
             auth: {
                 strategy: 'api-token',
                 mode: 'required'
@@ -54,20 +61,47 @@ async function init(args) {
                     license: Joi.string().example(packageData.license).description('EmailEngine license'),
                     accounts: Joi.number().integer().example(26).description('Number of registered accounts'),
                     node: Joi.string().example('16.10.0').description('Node.js Version'),
-                    redis: Joi.string().example('6.2.4').description('Redis Version'),
+                    redis: Joi.string()
+                        .example('6.2.4')
+                        .description('Redis version. Can include the server software in parentheses, or an error message if the version lookup failed'),
+                    redisSoftware: Joi.string().example('redis').description('Redis-compatible server software name'),
+                    redisCluster: Joi.boolean().example(false).description('Whether Redis is running in cluster mode'),
+                    redisWarnings: Joi.array()
+                        .items(
+                            Joi.object({
+                                key: Joi.string().example('maxmemory-policy').description('Warning identifier'),
+                                color: Joi.string().example('warning').description('Severity indicator'),
+                                title: Joi.string().example('Unsafe Redis eviction policy').description('Warning title'),
+                                details: Joi.array().items(Joi.string()).description('Warning details')
+                            })
+                                .unknown()
+                                .label('RedisWarningEntry')
+                        )
+                        .description('Warnings about the Redis configuration')
+                        .label('RedisWarnings'),
+                    redisPing: Joi.number().description('Redis latency in milliseconds'),
+                    imapflow: Joi.string().example('1.0.188').description('ImapFlow version'),
+                    bullmq: Joi.string().example('5.0.0').description('BullMQ version'),
+                    arch: Joi.string().example('arm64').description('CPU architecture of the host'),
+                    build: Joi.object().unknown().description('Build information for the running EmailEngine instance').label('BuildInfo'),
+                    queues: Joi.object().unknown().description('Job counters for the notify, submit, and documents queues').label('QueueStats'),
                     connections: Joi.object({
                         init: Joi.number().integer().example(2).description('Accounts not yet initialized'),
                         connected: Joi.number().integer().example(8).description('Successfully connected accounts'),
                         connecting: Joi.number().integer().example(7).description('Connection is being established'),
+                        syncing: Joi.number().integer().example(1).description('Accounts that are currently syncing'),
                         authenticationError: Joi.number().integer().example(3).description('Authentication failed'),
                         connectError: Joi.number().integer().example(5).description('Connection failed due to technical error'),
                         unset: Joi.number().integer().example(0).description('Accounts without valid IMAP settings'),
-                        disconnected: Joi.number().integer().example(1).description('IMAP connection was closed')
+                        disconnected: Joi.number().integer().example(1).description('IMAP connection was closed'),
+                        paused: Joi.number().integer().example(0).description('Accounts that are paused'),
+                        unassigned: Joi.number().integer().example(0).description('Accounts not assigned to any worker')
                     })
+                        .unknown()
                         .description('Counts of accounts in different connection states')
                         .label('ConnectionsStats'),
                     counters: Joi.object().label('CounterStats').unknown()
-                }).label('SettingsResponse'),
+                }).label('StatsResponse'),
                 failAction: 'log'
             }
         }

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

@@ -15,7 +15,9 @@ const {
     accountIdSchema,
     templateSchemas,
     settingsSchema,
-    ipSchema
+    ipSchema,
+    threadIdSchema,
+    errorResponses
 } = require('../schemas');
 
 async function init(args) {
@@ -65,7 +67,11 @@ async function init(args) {
             notes: 'Submit message for delivery. If reference message ID is provided then EmailEngine adds all headers and flags required for a reply/forward automatically.',
             tags: ['api', 'Submit'],
 
-            plugins: {},
+            plugins: {
+                'hapi-swagger': {
+                    responses: errorResponses(400, 401, 403, 404, 429, 500, 503)
+                }
+            },
 
             auth: {
                 strategy: 'api-token',
@@ -378,9 +384,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('SubmitResponseReferenceThreadId'),
                         documentStore: Joi.boolean()
                             .example(true)
                             .description('Was the message data loaded from the Document Store')
@@ -395,47 +401,34 @@ async function init(args) {
                     preview: Joi.string()
                         .base64()
                         .example('Q29udGVudC1UeXBlOiBtdWx0aX...')
-                        .description('Base64 encoded RFC822 email if a preview was requested')
+                        .description('Base64 encoded RFC822 email if a preview was requested. Not returned for mail-merge submissions.')
                         .label('ResponsePreview'),
 
+                    idempotency: Joi.object({
+                        key: idempotencyKeySchema.example('submit-12345').description('Idempotency key from the request').label('ResponseIdempotencyKey'),
+                        status: Joi.string()
+                            .valid('MISS', 'HIT')
+                            .example('MISS')
+                            .description('Whether the response was generated now (MISS) or returned from the idempotency cache (HIT)')
+                    })
+                        .description('Idempotency info, present when an Idempotency-Key header was used')
+                        .label('ResponseIdempotency'),
+
                     mailMerge: Joi.array()
                         .items(
                             Joi.object({
-                                success: Joi.boolean()
-                                    .example(true)
-                                    .description('Was the referenced message processed successfully')
-                                    .label('ResponseReferenceSuccess'),
+                                success: Joi.boolean().example(true).description('Was the message queued successfully').label('ResponseReferenceSuccess'),
                                 to: addressSchema.label('ToAddressSingle'),
                                 messageId: Joi.string().max(996).example('<test123@example.com>').description('Message ID'),
-                                queueId: Joi.string()
-                                    .example('d41f0423195f271f')
-                                    .description('Queue identifier for scheduled email. Not present for bulk messages.'),
-                                reference: Joi.object({
-                                    message: Joi.string()
-                                        .base64({ paddingRequired: false, urlSafe: true })
-                                        .max(256)
-                                        .required()
-                                        .example('AAAAAQAACnA')
-                                        .description('Referenced message ID'),
-                                    documentStore: Joi.boolean()
-                                        .example(true)
-                                        .description('Was the message data loaded from the Document Store')
-                                        .label('ResponseDocumentStore')
-                                        .meta({ swaggerHidden: true }),
-                                    success: Joi.boolean()
-                                        .example(true)
-                                        .description('Was the referenced message processed successfully')
-                                        .label('ResponseReferenceSuccess'),
-                                    error: Joi.string()
-                                        .example('Referenced message was not found')
-                                        .description('An error message if referenced message processing failed')
-                                })
-                                    .description('Reference info if referencing was requested')
-                                    .label('ResponseReference'),
-                                sendAt: Joi.date()
-                                    .iso()
-                                    .example('2021-07-08T07:06:34.336Z')
-                                    .description('Send message at specified time. Overrides message level `sendAt` value.'),
+                                queueId: Joi.string().example('d41f0423195f271f').description('Queue identifier for the scheduled email'),
+                                sendAt: Joi.date().iso().example('2021-07-08T07:06:34.336Z').description('Scheduled send time for this recipient'),
+                                error: Joi.string().example('Failed to queue message').description('Error message if queueing failed for this recipient'),
+                                code: Joi.string().example('EENVELOPE').description('Error code if queueing failed for this recipient'),
+                                statusCode: Joi.number()
+                                    .integer()
+                                    .allow(null)
+                                    .example(500)
+                                    .description('Error status code if queueing failed for this recipient'),
                                 skipped: Joi.object({
                                     reason: Joi.string().example('unsubscribe').description('Why this message was skipped'),
                                     listId: Joi.string().example('test-list')
@@ -452,10 +445,6 @@ async function init(args) {
                                     },
                                     messageId: '<19b9c433-d428-f6d8-1d00-d666ebcadfc4@ekiri.ee>',
                                     queueId: '1812477338914c8372a',
-                                    reference: {
-                                        message: 'AAAAAQAACnA',
-                                        success: true
-                                    },
                                     sendAt: '2021-07-08T07:06:34.336Z'
                                 })
                                 .unknown()