emailengine-app 2.69.0 → 2.71.0

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

@@ -4,7 +4,7 @@ const crypto = require('crypto');
 const { redis } = require('../db');
 const { Account } = require('../account');
 const getSecret = require('../get-secret');
-const { oauth2Apps, SERVICE_ACCOUNT_PROVIDERS } = require('../oauth2-apps');
+const { oauth2Apps, LEGACY_KEYS, SERVICE_ACCOUNT_PROVIDERS } = require('../oauth2-apps');
 const settings = require('../settings');
 const { autodetectImapSettings } = require('../autodetect-imap-settings');
 const Boom = require('@hapi/boom');
@@ -26,11 +26,42 @@ const {
     oauth2Schema,
     oauth2UpdateSchema,
     defaultAccountTypeSchema,
-    shortMailboxesSchema
+    shortMailboxesSchema,
+    ACCOUNT_DISPLAY_STATES,
+    errorResponses
 } = require('../schemas');
 
 const { REDIS_PREFIX, MAX_FORM_TTL, NONCE_BYTES } = require('../consts');
 
+// OAuth2 scope list stored on the account (accountData.oauth2.scope). Reused with a per-route
+// description/label where the same value is exposed under a different field name
+const accountOauth2ScopesSchema = Joi.array()
+    .items(Joi.string().example('https://mail.google.com/').label('AccountScopeEntry'))
+    .description('OAuth2 scopes granted for this account')
+    .label('AccountOauth2Scopes');
+
+// Per-protocol result block for the account verification response - the IMAP and SMTP results
+// carry the same fields built by verifyAccountInfo, only labels, wording, and the server
+// response example differ
+const verifyResultSchema = (proto, responseTextExample) =>
+    Joi.object({
+        success: Joi.boolean().example(true).description(`Was ${proto.toUpperCase()} account verified`).label(`Verify${proto}Success`),
+        error: Joi.string()
+            .example('Something went wrong')
+            .description(`Error messages for ${proto.toUpperCase()} verification. Only present if success=false`)
+            .label(`Verify${proto}Error`),
+        code: Joi.string().example('ERR_SSL_WRONG_VERSION_NUMBER').description('Error code. Only present if success=false').label(`Verify${proto}Code`),
+        statusCode: Joi.number()
+            .integer()
+            .example(500)
+            .description('HTTP-style status code for the error. Only present if success=false')
+            .label(`Verify${proto}StatusCode`),
+        responseText: Joi.string()
+            .example(responseTextExample)
+            .description('Server response for the failed verification. Only present if success=false')
+            .label(`Verify${proto}ResponseText`)
+    }).label(`Verify${proto}Result`);
+
 /**
  * Validates that delegation fields are only used with OAuth2 accounts.
  */
@@ -149,7 +180,11 @@ async function init(args) {
             notes: 'Registers new IMAP account to be synced',
             tags: ['api', 'Account'],
 
-            plugins: {},
+            plugins: {
+                'hapi-swagger': {
+                    responses: errorResponses(400, 401, 403, 404, 429, 500)
+                }
+            },
 
             auth: {
                 strategy: 'api-token',
@@ -247,13 +282,19 @@ async function init(args) {
 
             response: {
                 schema: Joi.object({
-                    account: accountIdSchema.required(),
+                    account: accountIdSchema,
                     state: Joi.string()
-                        .required()
                         .valid('existing', 'new')
                         .example('new')
-                        .description('Is the account new or updated existing')
-                        .label('CreateAccountState')
+                        .description('Is the account new or updated existing. Not present when a redirect URL is returned')
+                        .label('CreateAccountState'),
+                    redirect: Joi.string()
+                        .uri()
+                        .example('https://emailengine.example.com/oauth?account=example')
+                        .description(
+                            'OAuth2 authorization URL. Returned instead of account and state when the request used oauth2.authorize=true - send the user to this URL to complete the OAuth2 flow'
+                        )
+                        .label('CreateAccountRedirect')
                 }).label('CreateAccountResponse'),
                 failAction: 'log'
             }
@@ -288,7 +329,11 @@ async function init(args) {
             notes: 'Updates account information',
             tags: ['api', 'Account'],
 
-            plugins: {},
+            plugins: {
+                'hapi-swagger': {
+                    responses: errorResponses(400, 401, 403, 404, 429, 500)
+                }
+            },
 
             auth: {
                 strategy: 'api-token',
@@ -396,7 +441,11 @@ async function init(args) {
             notes: 'Requests connection to be reconnected',
             tags: ['api', 'Account'],
 
-            plugins: {},
+            plugins: {
+                'hapi-swagger': {
+                    responses: errorResponses(400, 401, 403, 404, 429, 500)
+                }
+            },
 
             auth: {
                 strategy: 'api-token',
@@ -455,7 +504,11 @@ async function init(args) {
             notes: 'Immediately trigger account syncing for IMAP accounts',
             tags: ['api', 'Account'],
 
-            plugins: {},
+            plugins: {
+                'hapi-swagger': {
+                    responses: errorResponses(400, 401, 403, 404, 429, 500)
+                }
+            },
 
             auth: {
                 strategy: 'api-token',
@@ -516,7 +569,11 @@ async function init(args) {
 
             tags: ['api', 'Account'],
 
-            plugins: {},
+            plugins: {
+                'hapi-swagger': {
+                    responses: errorResponses(400, 401, 403, 404, 429, 500)
+                }
+            },
 
             auth: {
                 strategy: 'api-token',
@@ -583,7 +640,11 @@ async function init(args) {
             notes: 'Deletes all email indexes from Redis and ElasticSearch and re-creates the index for that account. You can only run a single flush operation at a time, so you must wait until the previous flush has finished before initiating a new one.',
             tags: ['api', 'Account'],
 
-            plugins: {},
+            plugins: {
+                'hapi-swagger': {
+                    responses: errorResponses(400, 401, 403, 404, 429, 500)
+                }
+            },
 
             auth: {
                 strategy: 'api-token',
@@ -646,7 +707,11 @@ async function init(args) {
             notes: 'Lists registered accounts',
             tags: ['api', 'Account'],
 
-            plugins: {},
+            plugins: {
+                'hapi-swagger': {
+                    responses: errorResponses(400, 401, 403, 429, 500)
+                }
+            },
 
             auth: {
                 strategy: 'api-token',
@@ -673,7 +738,7 @@ async function init(args) {
                         .label('PageNumber'),
                     pageSize: Joi.number().integer().min(1).max(1000).default(20).example(20).description('How many entries per page').label('PageSize'),
                     state: Joi.string()
-                        .valid('init', 'syncing', 'connecting', 'connected', 'authenticationError', 'connectError', 'unset', 'disconnected')
+                        .valid(...ACCOUNT_DISPLAY_STATES)
                         .example('connected')
                         .description('Filter accounts by state')
                         .label('AccountState'),
@@ -687,17 +752,27 @@ async function init(args) {
                     page: Joi.number().integer().example(0).description('Current page (0-based index)').label('PageNumber'),
                     pages: Joi.number().integer().example(24).description('Total page count').label('PagesNumber'),
 
+                    query: Joi.string()
+                        .allow(false)
+                        .example(false)
+                        .description('Search term used for filtering, or false when no filter was applied')
+                        .label('AccountsQueryFilter'),
+                    state: Joi.string()
+                        .example('*')
+                        .description('Account state filter used for the listing, or "*" when no filter was applied')
+                        .label('AccountsStateFilter'),
+
                     accounts: Joi.array()
                         .items(
                             Joi.object({
                                 account: accountIdSchema.required(),
-                                name: Joi.string().max(256).example('My Email Account').description('Display name for the account'),
+                                name: Joi.string().allow('').max(256).example('My Email Account').description('Display name for the account'),
                                 email: Joi.string().empty('').email().example('user@example.com').description('Default email address of the account'),
                                 type: AccountTypeSchema,
                                 app: Joi.string().max(256).example('AAABhaBPHscAAAAH').description('OAuth2 application ID'),
                                 state: Joi.string()
                                     .required()
-                                    .valid('init', 'syncing', 'connecting', 'connected', 'authenticationError', 'connectError', 'unset', 'disconnected')
+                                    .valid(...ACCOUNT_DISPLAY_STATES)
                                     .example('connected')
                                     .description('Account state')
                                     .label('AccountListState'),
@@ -713,8 +788,11 @@ async function init(args) {
 
                                 counters: accountCountersSchema,
 
-                                syncTime: Joi.date().iso().example('2021-02-17T13:43:18.860Z').description('Last sync time'),
-                                lastError: lastErrorSchema.allow(null)
+                                syncTime: Joi.date().iso().example('2021-02-17T13:43:18.860Z').description('Last sync time (IMAP accounts only)'),
+                                lastError: lastErrorSchema.allow(null),
+                                delegationError: Joi.string()
+                                    .example('Delegated account was not found')
+                                    .description('Error message if the delegated account could not be resolved')
                             }).label('AccountResponseItem')
                         )
                         .label('AccountEntries')
@@ -817,16 +895,15 @@ async function init(args) {
                     oauth2App = await oauth2Apps.get(accountData.oauth2.provider);
 
                     if (oauth2App) {
+                        result.type = oauth2App.provider;
                         // Check if account is already marked as send-only
                         if (accountData.sendOnly) {
                             result.sendOnly = true;
-                        } else {
-                            result.type = oauth2App.provider;
                         }
                         if (oauth2App.id !== oauth2App.provider) {
                             result.app = oauth2App.id;
                         }
-                        result.baseScopes = oauth2App.baseScope || 'imap';
+                        result.baseScopes = oauth2App.baseScopes || 'imap';
                     } else {
                         result.type = 'oauth2';
                     }
@@ -869,6 +946,12 @@ async function init(args) {
             notes: 'Returns stored information about the account. Passwords are not included.',
             tags: ['api', 'Account'],
 
+            plugins: {
+                'hapi-swagger': {
+                    responses: errorResponses(400, 401, 403, 404, 429, 500)
+                }
+            },
+
             auth: {
                 strategy: 'api-token',
                 mode: 'required'
@@ -901,7 +984,7 @@ async function init(args) {
                 schema: Joi.object({
                     account: accountIdSchema.required(),
 
-                    name: Joi.string().max(256).example('My Email Account').description('Display name for the account'),
+                    name: Joi.string().allow('').max(256).example('My Email Account').description('Display name for the account'),
                     email: Joi.string().empty('').email().example('user@example.com').description('Default email address of the account'),
 
                     copy: Joi.boolean().example(true).description('Copy submitted messages to Sent folder'),
@@ -917,6 +1000,7 @@ async function init(args) {
                     subconnections: accountSchemas.subconnections,
 
                     webhooks: Joi.string()
+                        .allow('')
                         .uri({
                             scheme: ['http', 'https'],
                             allowRelative: false
@@ -930,10 +1014,22 @@ async function init(args) {
 
                     smtp: Joi.object(smtpSchema).description('SMTP configuration').label('SMTPResponse'),
 
-                    oauth2: Joi.object(oauth2Schema).description('OAuth2 configuration').label('Oauth2Response'),
+                    oauth2: Joi.object(oauth2Schema)
+                        .keys({
+                            scope: accountOauth2ScopesSchema,
+                            tokenType: Joi.string().example('Bearer').description('OAuth2 token type'),
+                            generated: Joi.date().iso().example('2021-03-22T13:13:31.000Z').description('When the current access token was generated'),
+                            refreshTokenGenerated: Joi.date()
+                                .iso()
+                                .example('2021-03-22T13:13:31.000Z')
+                                .description('When the current refresh token was generated'),
+                            userFlag: Joi.object().unknown().description('Account-level OAuth2 error flag, if any').label('AccountOauth2UserFlag')
+                        })
+                        .description('OAuth2 configuration')
+                        .label('Oauth2Response'),
 
                     state: Joi.string()
-                        .valid('init', 'syncing', 'connecting', 'connected', 'authenticationError', 'connectError', 'unset', 'disconnected')
+                        .valid(...ACCOUNT_DISPLAY_STATES)
                         .example('connected')
                         .description('Informational account state')
                         .label('AccountInfoState'),
@@ -949,11 +1045,30 @@ async function init(args) {
                         description: Joi.string().example('Authentication failed').description('Error information'),
                         responseCode: Joi.number().integer().example(500).description('Error status code'),
                         code: Joi.string().example('EAUTH').description('Error type identifier'),
-                        command: Joi.string().example('AUTH PLAIN').description('SMTP command that failed')
+                        command: Joi.string().example('AUTH PLAIN').description('SMTP command that failed'),
+                        networkRouting: Joi.object()
+                            .unknown()
+                            .allow(null)
+                            .description('Network routing information for the delivery attempt')
+                            .label('SMTPStatusNetworkRouting')
                     })
-                        .description('Information about the last SMTP connection attempt')
+                        .allow(null)
+                        .description('Information about the last SMTP connection attempt. Null when no SMTP connection has been attempted')
                         .label('SMTPInfoStatus'),
 
+                    syncError: Joi.object({
+                        path: Joi.string().example('INBOX').description('Mailbox folder path where the error occurred'),
+                        time: Joi.date().iso().example('2021-07-08T07:06:34.336Z').description('When the error occurred'),
+                        error: Joi.string().example('Failed to open mailbox').description('Error message')
+                    })
+                        .unknown()
+                        .description('Information about the last mailbox sync error (IMAP accounts only)')
+                        .label('AccountSyncError'),
+
+                    connections: Joi.number().integer().example(2).description('Number of open IMAP connections for this account (IMAP accounts only)'),
+
+                    sendOnly: Joi.boolean().example(false).description('Whether this is a send-only account that does not sync messages'),
+
                     webhooksCustomHeaders: settingsSchema.webhooksCustomHeaders.label('AccountWebhooksCustomHeaders'),
 
                     locale: Joi.string().empty('').max(100).example('fr').description('Optional locale'),
@@ -982,17 +1097,23 @@ async function init(args) {
                             'Account quota information if query argument quota=true. This value will be false if the server does not provide quota information.'
                         ),
 
-                    syncTime: Joi.date().iso().example('2021-02-17T13:43:18.860Z').description('Last sync time'),
+                    syncTime: Joi.date().iso().example('2021-02-17T13:43:18.860Z').description('Last sync time (IMAP accounts only)'),
 
                     outlookSubscription: Joi.object({
                         id: Joi.string().description('Microsoft Graph subscription ID'),
-                        expirationDateTime: Joi.date().iso().description('When the subscription expires'),
+                        expirationDateTime: Joi.date().iso().allow(null).description('When the subscription expires'),
                         state: Joi.object({
-                            state: Joi.string().valid('creating', 'created', 'error').description('Subscription state'),
+                            state: Joi.string().valid('creating', 'created', 'renewing', 'error').description('Subscription state'),
                             time: Joi.number().description('Timestamp of last state change'),
-                            error: Joi.string().description('Error message if state is error')
-                        }).description('Current subscription state')
-                    }).description('Microsoft Graph subscription details (Outlook accounts only)'),
+                            error: Joi.string().allow(null).description('Error message if state is error, null after a successful renewal'),
+                            retryCount: Joi.number().integer().description('How many times the subscription renewal has been retried'),
+                            createRetryCount: Joi.number().integer().description('How many times the subscription creation has been retried')
+                        })
+                            .unknown()
+                            .description('Current subscription state')
+                    })
+                        .unknown()
+                        .description('Microsoft Graph subscription details (Outlook accounts only)'),
 
                     lastError: lastErrorSchema.allow(null)
                 }).label('AccountResponse'),
@@ -1024,6 +1145,19 @@ async function init(args) {
             try {
                 const tokenData = await accountObject.getActiveAccessTokenData();
 
+                // Account data stores the OAuth2 app ID as the provider value. Resolve it to the
+                // provider name and expose the app ID separately. Legacy app IDs already equal
+                // their provider name, so skip the lookup for these.
+                if (tokenData.provider && !LEGACY_KEYS.includes(tokenData.provider)) {
+                    let oauth2App = await oauth2Apps.get(tokenData.provider);
+                    if (oauth2App) {
+                        if (oauth2App.id !== oauth2App.provider) {
+                            tokenData.app = oauth2App.id;
+                        }
+                        tokenData.provider = oauth2App.provider;
+                    }
+                }
+
                 // Record metric if token was actually refreshed (not cached)
                 if (!tokenData.cached) {
                     const provider = tokenData.provider || 'unknown';
@@ -1045,7 +1179,11 @@ async function init(args) {
             notes: 'Get the active OAuth2 access token for an account. NB! This endpoint is disabled by default and needs activation on the Service configuration page.',
             tags: ['api', 'Account'],
 
-            plugins: {},
+            plugins: {
+                'hapi-swagger': {
+                    responses: errorResponses(400, 401, 403, 404, 429, 500)
+                }
+            },
 
             auth: {
                 strategy: 'api-token',
@@ -1069,8 +1207,16 @@ async function init(args) {
                 schema: Joi.object({
                     account: accountIdSchema.required(),
                     user: Joi.string().max(256).required().example('user@example.com').description('Username'),
-                    accessToken: Joi.string().max(256).required().example('aGVsbG8gd29ybGQ=').description('Access Token').label('OAuthAccessToken'),
-                    provider: OAuth2ProviderSchema
+                    accessToken: Joi.string()
+                        .max(4 * 4096)
+                        .example('aGVsbG8gd29ybGQ=')
+                        .description('Access Token. Can be missing if the external authentication server provided password-based credentials')
+                        .label('OAuthAccessToken'),
+                    provider: OAuth2ProviderSchema,
+                    app: Joi.string().max(256).example('AAABhaBPHscAAAAH').description('OAuth2 application ID'),
+                    registeredScopes: accountOauth2ScopesSchema.description('OAuth2 scopes registered for this account').label('RegisteredScopes'),
+                    expires: Joi.date().iso().example('2021-03-22T13:13:31.000Z').description('When the access token expires'),
+                    cached: Joi.boolean().example(false).description('Whether the token was returned from cache or was freshly renewed')
                 }).label('AccountTokenResponse'),
                 failAction: 'log'
             }
@@ -1101,7 +1247,11 @@ async function init(args) {
             notes: 'Returns signatures associated with the account. Currently only Gmail is supported, and only "new message" signatures from the "sendAs" list are returned.',
             tags: ['api', 'Account'],
 
-            plugins: {},
+            plugins: {
+                'hapi-swagger': {
+                    responses: errorResponses(400, 401, 403, 404, 429, 500)
+                }
+            },
 
             auth: {
                 strategy: 'api-token',
@@ -1130,7 +1280,10 @@ async function init(args) {
                                 signature: Joi.string().example('<div>Best regards,</div>').description('Signature HTML code').required()
                             }).label('SignatureResponseItem')
                         )
-                        .label('SignatureEntries')
+                        .label('SignatureEntries'),
+                    signaturesSupported: Joi.boolean()
+                        .example(true)
+                        .description('Whether the account type supports listing signatures (currently Gmail API accounts only)')
                 }).label('AccountSignaturesResponse'),
                 failAction: 'log'
             }
@@ -1205,7 +1358,11 @@ async function init(args) {
             notes: 'Generates a redirect link to the hosted authentication form',
             tags: ['api', 'Account'],
 
-            plugins: {},
+            plugins: {
+                'hapi-swagger': {
+                    responses: errorResponses(400, 401, 403, 404, 429, 500)
+                }
+            },
 
             auth: {
                 strategy: 'api-token',
@@ -1299,7 +1456,8 @@ async function init(args) {
 
             plugins: {
                 'hapi-swagger': {
-                    produces: ['text/plain']
+                    produces: ['text/plain'],
+                    responses: errorResponses(400, 401, 403, 429, 500)
                 }
             },
 
@@ -1334,7 +1492,11 @@ async function init(args) {
             notes: 'Checks if can connect and authenticate using provided account info',
             tags: ['api', 'Account'],
 
-            plugins: {},
+            plugins: {
+                'hapi-swagger': {
+                    responses: errorResponses(400, 401, 403, 429, 500)
+                }
+            },
 
             auth: {
                 strategy: 'api-token',
@@ -1360,28 +1522,8 @@ async function init(args) {
             },
             response: {
                 schema: Joi.object({
-                    imap: Joi.object({
-                        success: Joi.boolean().example(true).description('Was IMAP account verified').label('VerifyImapSuccess'),
-                        error: Joi.string()
-                            .example('Something went wrong')
-                            .description('Error messages for IMAP verification. Only present if success=false')
-                            .label('VerifyImapError'),
-                        code: Joi.string()
-                            .example('ERR_SSL_WRONG_VERSION_NUMBER')
-                            .description('Error code. Only present if success=false')
-                            .label('VerifyImapCode')
-                    }).label('VerifyImapResult'),
-                    smtp: Joi.object({
-                        success: Joi.boolean().example(true).description('Was SMTP account verified').label('VerifySmtpSuccess'),
-                        error: Joi.string()
-                            .example('Something went wrong')
-                            .description('Error messages for SMTP verification. Only present if success=false')
-                            .label('VerifySmtpError'),
-                        code: Joi.string()
-                            .example('ERR_SSL_WRONG_VERSION_NUMBER')
-                            .description('Error code. Only present if success=false')
-                            .label('VerifySmtpCode')
-                    }).label('VerifySmtpResult'),
+                    imap: verifyResultSchema('Imap', 'NO [AUTHENTICATIONFAILED] Invalid credentials'),
+                    smtp: verifyResultSchema('Smtp', '535 Authentication failed'),
                     mailboxes: shortMailboxesSchema
                 }).label('VerifyAccountResponse'),
                 failAction: 'log'
@@ -1411,7 +1553,11 @@ async function init(args) {
             notes: 'Try to discover IMAP and SMTP settings for an email account',
             tags: ['api', 'Settings'],
 
-            plugins: {},
+            plugins: {
+                'hapi-swagger': {
+                    responses: errorResponses(400, 401, 403, 429, 500)
+                }
+            },
 
             auth: {
                 strategy: 'api-token',
@@ -1444,31 +1590,45 @@ async function init(args) {
                             user: Joi.string().max(256).example('myuser@gmail.com').description('Account username')
                         }).label('DetectedAuthenticationInfo'),
 
-                        host: Joi.string().hostname().required().example('imap.gmail.com').description('Hostname to connect to'),
+                        host: Joi.string().hostname().example('imap.gmail.com').description('Hostname to connect to'),
                         port: Joi.number()
                             .integer()
                             .min(1)
                             .max(64 * 1024)
-                            .required()
                             .example(993)
                             .description('Service port number'),
                         secure: Joi.boolean().default(false).example(true).description('Should connection use TLS. Usually true for port 993')
-                    }).label('ResolvedServerSettings'),
+                    })
+                        .allow(false)
+                        .description('Discovered IMAP settings. False if IMAP settings were not found')
+                        .label('ResolvedServerSettings'),
                     smtp: Joi.object({
                         auth: Joi.object({
                             user: Joi.string().max(256).example('myuser@gmail.com').description('Account username')
                         }).label('DetectedAuthenticationInfo'),
 
-                        host: Joi.string().hostname().required().example('imap.gmail.com').description('Hostname to connect to'),
+                        host: Joi.string().hostname().example('smtp.gmail.com').description('Hostname to connect to'),
                         port: Joi.number()
                             .integer()
                             .min(1)
                             .max(64 * 1024)
-                            .required()
-                            .example(993)
+                            .example(465)
                             .description('Service port number'),
-                        secure: Joi.boolean().default(false).example(true).description('Should connection use TLS. Usually true for port 993')
-                    }).label('DiscoveredServerSettings'),
+                        secure: Joi.boolean().default(false).example(true).description('Should connection use TLS. Usually true for port 465')
+                    })
+                        .allow(false)
+                        .description('Discovered SMTP settings. False if SMTP settings were not found')
+                        .label('DiscoveredServerSettings'),
+                    appPassword: Joi.object({
+                        required: Joi.boolean().example(true).description('Whether the provider requires an app password'),
+                        provider: Joi.string().example('Gmail').description('Provider name'),
+                        instructions: Joi.string()
+                            .example('Use an app password instead of the regular account password')
+                            .description('Instructions for setting up an app password')
+                    })
+                        .unknown()
+                        .description('App password requirements for the provider, if known')
+                        .label('DiscoveredAppPasswordInfo'),
                     _source: Joi.string().example('srv').description('Source for the detected info')
                 }).label('DiscoveredEmailSettings'),
                 failAction: 'log'

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

@@ -8,7 +8,7 @@ const getSecret = require('../get-secret');
 const { lists } = require('../lists');
 const { failAction } = require('../tools');
 const { handleError } = require('./route-helpers');
-const { accountIdSchema } = require('../schemas');
+const { accountIdSchema, errorResponses } = require('../schemas');
 const { REDIS_PREFIX } = require('../consts');
 
 async function init(args) {
@@ -31,7 +31,11 @@ async function init(args) {
             notes: 'List blocklists with blocked addresses',
             tags: ['api', 'Blocklists'],
 
-            plugins: {},
+            plugins: {
+                'hapi-swagger': {
+                    responses: errorResponses(400, 401, 403, 429, 500)
+                }
+            },
 
             auth: {
                 strategy: 'api-token',
@@ -97,7 +101,11 @@ async function init(args) {
             notes: 'List blocked addresses for a list',
             tags: ['api', 'Blocklists'],
 
-            plugins: {},
+            plugins: {
+                'hapi-swagger': {
+                    responses: errorResponses(400, 401, 403, 404, 429, 500)
+                }
+            },
 
             auth: {
                 strategy: 'api-token',
@@ -145,10 +153,10 @@ async function init(args) {
                         .items(
                             Joi.object({
                                 recipient: Joi.string().email().example('user@example.com').description('Listed email address').required(),
-                                account: accountIdSchema.required().required(),
+                                account: accountIdSchema.required(),
                                 messageId: Joi.string().example('<test123@example.com>').description('Message ID'),
                                 source: Joi.string().example('api').description('Which mechanism was used to add the entry'),
-                                reason: Joi.string().example('api').description('Why this entry was added'),
+                                reason: Joi.string().example('block').description('Why this entry was added'),
                                 remoteAddress: Joi.string()
                                     .ip({
                                         version: ['ipv4', 'ipv6'],
@@ -203,18 +211,7 @@ async function init(args) {
                     added: !!added
                 };
             } 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;
-                }
-                if (err.details) {
-                    error.output.payload.details = err.details;
-                }
-                throw error;
+                handleError(request, err);
             }
         },
         options: {
@@ -222,6 +219,12 @@ async function init(args) {
             notes: 'Add an email address to a blocklist',
             tags: ['api', 'Blocklists'],
 
+            plugins: {
+                'hapi-swagger': {
+                    responses: errorResponses(400, 401, 403, 404, 429, 500)
+                }
+            },
+
             auth: {
                 strategy: 'api-token',
                 mode: 'required'
@@ -294,7 +297,11 @@ async function init(args) {
             notes: 'Delete a blocked email address from a list',
             tags: ['api', 'Blocklists'],
 
-            plugins: {},
+            plugins: {
+                'hapi-swagger': {
+                    responses: errorResponses(400, 401, 403, 404, 429, 500)
+                }
+            },
 
             auth: {
                 strategy: 'api-token',