emailengine-app 2.68.1 → 2.70.0

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

@@ -0,0 +1,111 @@
+'use strict';
+
+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) {
+    const { server, call, CORS_CONFIG } = args;
+
+    server.route({
+        method: 'GET',
+        path: '/v1/stats',
+
+        async handler(request) {
+            return await getStats(redis, call, request.query.seconds);
+        },
+
+        options: {
+            description: 'Return server stats',
+            tags: ['api', 'Stats'],
+
+            plugins: {
+                'hapi-swagger': {
+                    responses: errorResponses(400, 401, 403, 429, 500)
+                }
+            },
+
+            auth: {
+                strategy: 'api-token',
+                mode: 'required'
+            },
+            cors: CORS_CONFIG,
+
+            validate: {
+                options: {
+                    stripUnknown: false,
+                    abortEarly: false,
+                    convert: true
+                },
+                failAction,
+
+                query: Joi.object({
+                    seconds: Joi.number()
+                        .integer()
+                        .empty('')
+                        .min(0)
+                        .max(MAX_DAYS_STATS * 24 * 3600)
+                        .default(3600)
+                        .example(3600)
+                        .description('Duration for counters')
+                        .label('CounterSeconds')
+                }).label('ServerStats')
+            },
+
+            response: {
+                schema: Joi.object({
+                    version: Joi.string().example(packageData.version).description('EmailEngine version number'),
+                    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. 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'),
+                        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('StatsResponse'),
+                failAction: 'log'
+            }
+        }
+    });
+}
+
+module.exports = init;

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

@@ -0,0 +1,461 @@
+'use strict';
+
+const Boom = require('@hapi/boom');
+const Joi = require('joi');
+const { redis } = require('../db');
+const { Account } = require('../account');
+const getSecret = require('../get-secret');
+const { failAction } = require('../tools');
+const {
+    messageReferenceSchema,
+    fromAddressSchema,
+    addressSchema,
+    idempotencyKeySchema,
+    headerTimeoutSchema,
+    accountIdSchema,
+    templateSchemas,
+    settingsSchema,
+    ipSchema,
+    threadIdSchema,
+    errorResponses
+} = require('../schemas');
+
+async function init(args) {
+    const { server, call, CORS_CONFIG, MAX_ATTACHMENT_SIZE, MAX_BODY_SIZE, MAX_PAYLOAD_TIMEOUT } = args;
+
+    server.route({
+        method: 'POST',
+        path: '/v1/account/{account}/submit',
+
+        async handler(request) {
+            let accountObject = new Account({
+                redis,
+                account: request.params.account,
+                call,
+                secret: await getSecret(),
+                timeout: request.headers['x-ee-timeout']
+            });
+
+            try {
+                return await accountObject.queueMessage(request.payload, {
+                    source: 'api',
+                    idempotencyKey: request.headers['idempotency-key'],
+                    useStructuredFormat: request.query.useStructuredFormat
+                });
+            } 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.info) {
+                    error.output.payload.info = err.info;
+                }
+                throw error;
+            }
+        },
+        options: {
+            payload: {
+                maxBytes: MAX_BODY_SIZE,
+                timeout: MAX_PAYLOAD_TIMEOUT
+            },
+
+            description: 'Submit message for delivery',
+            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: {
+                'hapi-swagger': {
+                    responses: errorResponses(400, 401, 403, 404, 429, 500, 503)
+                }
+            },
+
+            auth: {
+                strategy: 'api-token',
+                mode: 'required'
+            },
+            cors: CORS_CONFIG,
+
+            validate: {
+                options: {
+                    stripUnknown: false,
+                    abortEarly: false,
+                    convert: true
+                },
+                failAction,
+
+                params: Joi.object({
+                    account: accountIdSchema.required()
+                }),
+
+                query: Joi.object({
+                    documentStore: Joi.boolean()
+                        .truthy('Y', 'true', '1')
+                        .falsy('N', 'false', 0)
+                        .default(false)
+                        .description('If enabled then fetch email used as a reference template from the Document Store'),
+                    useStructuredFormat: Joi.boolean()
+                        .truthy('Y', 'true', '1')
+                        .falsy('N', 'false', 0)
+                        .default(false)
+                        .description(
+                            'For MS Graph accounts: If true, uses structured JSON format (respects from field for shared mailboxes, breaks calendar invites and special MIME types). If false, sends as raw MIME (preserves calendar invites, ignores from field). Default is false (raw MIME).'
+                        )
+                }).label('SubmitQuery'),
+
+                headers: Joi.object({
+                    'x-ee-timeout': headerTimeoutSchema,
+                    'idempotency-key': idempotencyKeySchema
+                }).unknown(),
+
+                payload: Joi.object({
+                    reference: messageReferenceSchema,
+
+                    envelope: Joi.object({
+                        from: Joi.string().email().allow('').example('sender@example.com'),
+                        to: Joi.array().items(Joi.string().email().required().example('recipient@example.com')).single().label('SmtpEnvelopeTo')
+                    })
+                        .description(
+                            "An optional object specifying the SMTP envelope used during email transmission. If not provided, the envelope is automatically derived from the email's message headers. This is useful when you need the envelope addresses to differ from those in the email headers."
+                        )
+                        .label('SMTPEnvelope')
+                        .when('mailMerge', {
+                            is: Joi.exist().not(false, null),
+                            then: Joi.forbidden('y')
+                        }),
+
+                    raw: Joi.string()
+                        .base64()
+                        .max(MAX_ATTACHMENT_SIZE)
+                        .example('TUlNRS1WZXJzaW9uOiAxLjANClN1YmplY3Q6IGhlbGxvIHdvcmxkDQoNCkhlbGxvIQ0K')
+                        .description(
+                            'A Base64-encoded email message in RFC 822 format. If you provide other fields along with raw, those fields will override the corresponding values in the raw message.'
+                        )
+                        .label('RFC822Raw')
+                        .when('mailMerge', {
+                            is: Joi.exist().not(false, null),
+                            then: Joi.forbidden('y')
+                        }),
+
+                    from: fromAddressSchema,
+
+                    replyTo: Joi.array()
+                        .items(addressSchema.label('ReplyToAddress'))
+                        .single()
+                        .example([{ name: 'From Me', address: 'sender@example.com' }])
+                        .description('List of Reply-To addresses')
+                        .label('ReplyTo'),
+
+                    to: Joi.array()
+                        .items(addressSchema.label('ToAddress'))
+                        .single()
+                        .example([{ address: 'recipient@example.com' }])
+                        .description('List of recipient addresses')
+                        .label('ToAddressList')
+                        .when('mailMerge', {
+                            is: Joi.exist().not(false, null),
+                            then: Joi.forbidden('y')
+                        }),
+
+                    cc: Joi.array()
+                        .items(addressSchema.label('CcAddress'))
+                        .single()
+                        .description('List of CC addresses')
+                        .label('CcAddressList')
+                        .when('mailMerge', {
+                            is: Joi.exist().not(false, null),
+                            then: Joi.forbidden('y')
+                        }),
+
+                    bcc: Joi.array()
+                        .items(addressSchema.label('BccAddress'))
+                        .single()
+                        .description('List of BCC addresses')
+                        .label('BccAddressList')
+                        .when('mailMerge', {
+                            is: Joi.exist().not(false, null),
+                            then: Joi.forbidden('y')
+                        }),
+
+                    subject: templateSchemas.subject,
+                    text: templateSchemas.text,
+                    html: templateSchemas.html,
+                    previewText: templateSchemas.previewText,
+
+                    template: Joi.string().max(256).example('example').description('Stored template ID to load the email content from'),
+
+                    render: Joi.object({
+                        format: Joi.string()
+                            .valid('html', 'markdown')
+                            .default('html')
+                            .description('Markup language for HTML ("html" or "markdown")')
+                            .label('RenderFormat'),
+                        params: Joi.object().label('RenderValues').description('An object of variables for the template renderer')
+                    })
+                        .allow(false)
+                        .description('Template rendering options')
+                        .when('mailMerge', {
+                            is: Joi.exist().not(false, null),
+                            then: Joi.forbidden('y')
+                        })
+                        .label('TemplateRender'),
+
+                    mailMerge: Joi.array()
+                        .items(
+                            Joi.object({
+                                to: addressSchema.label('ToAddress').required(),
+                                messageId: Joi.string().max(996).example('<test123@example.com>').description('Message ID'),
+                                params: Joi.object().label('RenderValues').description('An object of variables for the template renderer'),
+                                sendAt: Joi.date()
+                                    .iso()
+                                    .example('2021-07-08T07:06:34.336Z')
+                                    .description('Send message at specified time. Overrides message level `sendAt` value.')
+                            }).label('MailMergeListEntry')
+                        )
+                        .min(1)
+                        .description(
+                            'Mail merge options. A separate email is generated for each recipient. Using mail merge disables `messageId`, `envelope`, `to`, `cc`, `bcc`, `render` keys for the message root.'
+                        )
+                        .label('MailMergeList'),
+
+                    attachments: Joi.array()
+                        .items(
+                            Joi.object({
+                                filename: Joi.string().max(256).example('transparent.gif'),
+                                content: Joi.string()
+                                    .base64()
+                                    .max(MAX_ATTACHMENT_SIZE)
+                                    .required()
+                                    .example('R0lGODlhAQABAIAAAP///wAAACwAAAAAAQABAAACAkQBADs=')
+                                    .description('Base64 formatted attachment file')
+                                    .when('reference', {
+                                        is: Joi.exist().not(false, null),
+                                        then: Joi.forbidden(),
+                                        otherwise: Joi.required()
+                                    }),
+
+                                contentType: Joi.string().lowercase().max(256).example('image/gif'),
+                                contentDisposition: Joi.string().lowercase().valid('inline', 'attachment').label('AttachmentContentDisposition'),
+                                cid: Joi.string().max(256).example('unique-image-id@localhost').description('Content-ID value for embedded images'),
+                                encoding: Joi.string().valid('base64').default('base64').label('AttachmentEncoding'),
+
+                                reference: Joi.string()
+                                    .base64({ paddingRequired: false, urlSafe: true })
+                                    .max(256)
+                                    .allow(false, null)
+                                    .example('AAAAAQAACnAcde')
+                                    .description(
+                                        'References an existing attachment by its ID instead of providing new attachment content. If this field is set, the `content` field must not be included. If not set, the `content` field is required.'
+                                    )
+                                    .label('AttachmentReference')
+                            }).label('UploadAttachment')
+                        )
+                        .description('List of attachments')
+                        .label('UploadAttachmentList'),
+
+                    messageId: Joi.string().max(996).example('<test123@example.com>').description('Message ID'),
+                    headers: Joi.object().label('CustomHeaders').description('Custom Headers').unknown().example({
+                        'X-My-Custom-Header': 'Custom header value'
+                    }),
+
+                    trackingEnabled: Joi.boolean()
+                        .example(false)
+                        .description('Should EmailEngine track clicks and opens for this message')
+                        .meta({ swaggerHidden: true }),
+
+                    trackOpens: Joi.boolean().example(false).description('Should EmailEngine track opens for this message'),
+                    trackClicks: Joi.boolean().example(false).description('Should EmailEngine track clicks for this message'),
+
+                    copy: Joi.boolean()
+                        .allow(null)
+                        .example(null)
+                        .description(
+                            "If set then either copies the message to the Sent Mail folder or not. If not set then uses the account's default setting."
+                        ),
+
+                    sentMailPath: Joi.string()
+                        .empty('')
+                        .max(1024)
+                        .example('Sent Mail')
+                        .description("Upload sent message to this folder. By default the account's Sent Mail folder is used."),
+
+                    locale: Joi.string().empty('').max(100).example('fr').description('Optional locale').label('MessageLocale'),
+                    tz: Joi.string().empty('').max(100).example('Europe/Tallinn').description('Optional timezone'),
+
+                    sendAt: Joi.date().iso().example('2021-07-08T07:06:34.336Z').description('Send message at specified time'),
+                    deliveryAttempts: Joi.number()
+                        .integer()
+                        .example(10)
+                        .description('How many delivery attempts to make until message is considered as failed'),
+                    gateway: Joi.string().max(256).example('example').description('Optional SMTP gateway ID for message routing').label('MessageGateway'),
+
+                    listId: Joi.string()
+                        .hostname()
+                        .example('test-list')
+                        .description(
+                            'List ID for Mail Merge. Must use a subdomain name format. Lists are registered ad-hoc, so a new identifier defines a new list.'
+                        )
+                        .label('ListID')
+                        .when('mailMerge', {
+                            is: Joi.exist().not(false, null),
+                            then: Joi.optional(),
+                            otherwise: Joi.forbidden()
+                        }),
+
+                    dsn: Joi.object({
+                        id: Joi.string().trim().empty('').max(256).description('The envelope identifier that would be included in the response (ENVID)'),
+                        return: Joi.string()
+                            .trim()
+                            .empty('')
+                            .valid('headers', 'full')
+                            .required()
+                            .description('Specifies if only headers or the entire body of the message should be included in the response (RET)')
+                            .label('DsnReturn'),
+                        notify: Joi.array()
+                            .single()
+                            .items(Joi.string().valid('never', 'success', 'failure', 'delay').label('NotifyEntry'))
+                            .description('Defines the conditions under which a DSN response should be sent')
+                            .label('DsnNotify'),
+                        recipient: Joi.string().trim().empty('').email().description('The email address the DSN should be sent (ORCPT)')
+                    })
+                        .description('Request DSN notifications')
+                        .label('DSN'),
+
+                    baseUrl: Joi.string()
+                        .trim()
+                        .empty('')
+                        .uri({
+                            scheme: ['http', 'https'],
+                            allowRelative: false
+                        })
+                        .example('https://customer123.myservice.com')
+                        .description('Optional base URL for trackers. This URL must point to your EmailEngine instance.'),
+
+                    proxy: settingsSchema.proxyUrl.description('Optional proxy URL to use when connecting to the SMTP server'),
+                    localAddress: ipSchema.description('Optional local IP address to bind to when connecting to the SMTP server'),
+
+                    dryRun: Joi.boolean()
+                        .truthy('Y', 'true', '1')
+                        .falsy('N', 'false', 0)
+                        .default(false)
+                        .description(
+                            'If true, then EmailEngine does not send the email and returns an RFC822 formatted email file. Tracking information is not added to the email.'
+                        )
+                        .label('Preview')
+                })
+                    .oxor('raw', 'html')
+                    .oxor('raw', 'text')
+                    .oxor('raw', 'text')
+                    .oxor('raw', 'attachments')
+                    .label('SubmitMessage')
+                    .example({
+                        to: [
+                            {
+                                name: 'Nyan Cat',
+                                address: 'nyan.cat@example.com'
+                            }
+                        ],
+                        subject: 'What a wonderful message!',
+                        text: 'Hello from myself!',
+                        html: '<p>Hello from myself!</p>',
+                        attachments: [
+                            {
+                                filename: 'transparent.gif',
+                                content: 'R0lGODlhAQABAIAAAP///wAAACwAAAAAAQABAAACAkQBADs=',
+                                contentType: 'image/gif'
+                            }
+                        ]
+                    })
+            },
+
+            response: {
+                schema: Joi.object({
+                    response: Joi.string().example('Queued for delivery'),
+                    messageId: Joi.string()
+                        .example('<a2184d08-a470-fec6-a493-fa211a3756e9@example.com>')
+                        .description('Message-ID header value. Not present for bulk messages.'),
+                    queueId: Joi.string().example('d41f0423195f271f').description('Queue identifier for scheduled email. Not present for bulk messages.'),
+                    sendAt: Joi.date().example('2021-07-08T07:06:34.336Z').description('Scheduled send time'),
+
+                    reference: Joi.object({
+                        message: Joi.string()
+                            .base64({ paddingRequired: false, urlSafe: true })
+                            .max(256)
+                            .example('AAAAAQAACnA')
+                            .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')
+                            .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'),
+
+                    preview: Joi.string()
+                        .base64()
+                        .example('Q29udGVudC1UeXBlOiBtdWx0aX...')
+                        .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 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 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')
+                                })
+                                    .description('Info about skipped message. If this value is set, then the message was not sent')
+                                    .label('SkippedMessageInfo')
+                            })
+                                .label('BulkResponseEntry')
+                                .example({
+                                    success: true,
+                                    to: {
+                                        name: 'Andris 2',
+                                        address: 'andris@ethereal.email'
+                                    },
+                                    messageId: '<19b9c433-d428-f6d8-1d00-d666ebcadfc4@ekiri.ee>',
+                                    queueId: '1812477338914c8372a',
+                                    sendAt: '2021-07-08T07:06:34.336Z'
+                                })
+                                .unknown()
+                        )
+                        .label('BulkResponseList')
+                        .description('Bulk message responses')
+                }).label('SubmitMessageResponse'),
+                failAction: 'log'
+            }
+        }
+    });
+}
+
+module.exports = init;