@omnizap-system/omnizap 2.5.12

package/server/email/emailAutomationRuntime.js

@@ -0,0 +1,225 @@
+import logger from '#logger';
+import { setQueueDepth } from '../../app/observability/metrics.js';
+import { claimEmailOutboxTask, completeEmailOutboxTask, countEmailOutboxByStatus, failEmailOutboxTask } from './emailOutboxRepository.js';
+import { isEmailTransportConfigured, sendEmailMessage } from './emailTransportService.js';
+
+const parseEnvBool = (value, fallback) => {
+  if (value === undefined || value === null || value === '') return fallback;
+  const normalized = String(value).trim().toLowerCase();
+  if (['1', 'true', 'yes', 'y', 'on'].includes(normalized)) return true;
+  if (['0', 'false', 'no', 'n', 'off'].includes(normalized)) return false;
+  return fallback;
+};
+
+const clampInt = (value, fallback, min, max) => {
+  const numeric = Number(value);
+  if (!Number.isFinite(numeric)) return fallback;
+  return Math.max(min, Math.min(max, Math.floor(numeric)));
+};
+
+const clampNumber = (value, fallback, min, max) => {
+  const numeric = Number(value);
+  if (!Number.isFinite(numeric)) return fallback;
+  return Math.max(min, Math.min(max, numeric));
+};
+
+const EMAIL_AUTOMATION_ENABLED = parseEnvBool(process.env.EMAIL_AUTOMATION_ENABLED, true);
+const EMAIL_AUTOMATION_WORKER_ENABLED = parseEnvBool(process.env.EMAIL_AUTOMATION_WORKER_ENABLED, true);
+const EMAIL_AUTOMATION_POLL_INTERVAL_MS = clampInt(process.env.EMAIL_AUTOMATION_POLL_INTERVAL_MS, 12_000, 1_000, 300_000);
+const EMAIL_AUTOMATION_IDLE_BACKOFF_MULTIPLIER = clampNumber(process.env.EMAIL_AUTOMATION_IDLE_BACKOFF_MULTIPLIER, 1.7, 1, 5);
+const EMAIL_AUTOMATION_IDLE_MAX_POLL_INTERVAL_MS = clampInt(process.env.EMAIL_AUTOMATION_IDLE_MAX_POLL_INTERVAL_MS, Math.max(60_000, EMAIL_AUTOMATION_POLL_INTERVAL_MS * 8), 1_000, 900_000);
+const EMAIL_AUTOMATION_IDLE_JITTER_PERCENT = clampInt(process.env.EMAIL_AUTOMATION_IDLE_JITTER_PERCENT, 12, 0, 60);
+const EMAIL_AUTOMATION_MAX_PER_TICK = clampInt(process.env.EMAIL_AUTOMATION_MAX_PER_TICK, 3, 1, 20);
+const EMAIL_AUTOMATION_RETRY_DELAY_SECONDS = clampInt(process.env.EMAIL_AUTOMATION_RETRY_DELAY_SECONDS, 120, 5, 86_400);
+
+let started = false;
+let stopping = false;
+let inFlight = false;
+let timerHandle = null;
+let nextDelayMs = EMAIL_AUTOMATION_POLL_INTERVAL_MS;
+
+const applyDelayJitter = (delayMs) => {
+  const baseDelay = Math.max(250, Math.floor(Number(delayMs) || 0));
+  if (EMAIL_AUTOMATION_IDLE_JITTER_PERCENT <= 0) return baseDelay;
+  const variation = (Math.random() * 2 - 1) * (EMAIL_AUTOMATION_IDLE_JITTER_PERCENT / 100);
+  return Math.max(250, Math.floor(baseDelay * (1 + variation)));
+};
+
+const refreshQueueDepthMetrics = async () => {
+  const [pending, processing, failed] = await Promise.all([countEmailOutboxByStatus('pending'), countEmailOutboxByStatus('processing'), countEmailOutboxByStatus('failed')]);
+  setQueueDepth('email_outbox_pending', pending);
+  setQueueDepth('email_outbox_processing', processing);
+  setQueueDepth('email_outbox_failed', failed);
+};
+
+const scheduleNextTick = (delayMs = EMAIL_AUTOMATION_POLL_INTERVAL_MS) => {
+  if (stopping || !started) return;
+  if (timerHandle) {
+    clearTimeout(timerHandle);
+    timerHandle = null;
+  }
+
+  timerHandle = setTimeout(() => {
+    timerHandle = null;
+    void runLoopOnce();
+  }, applyDelayJitter(delayMs));
+
+  if (typeof timerHandle?.unref === 'function') {
+    timerHandle.unref();
+  }
+};
+
+export const runEmailAutomationTick = async ({ maxPerTick = EMAIL_AUTOMATION_MAX_PER_TICK, retryDelaySeconds = EMAIL_AUTOMATION_RETRY_DELAY_SECONDS } = {}) => {
+  if (!EMAIL_AUTOMATION_ENABLED || !EMAIL_AUTOMATION_WORKER_ENABLED) {
+    return {
+      executed: false,
+      reason: 'disabled',
+      claimed: 0,
+      sent: 0,
+      failed: 0,
+    };
+  }
+
+  if (!isEmailTransportConfigured()) {
+    return {
+      executed: false,
+      reason: 'smtp_not_configured',
+      claimed: 0,
+      sent: 0,
+      failed: 0,
+    };
+  }
+
+  const safeMaxPerTick = clampInt(maxPerTick, EMAIL_AUTOMATION_MAX_PER_TICK, 1, 20);
+  const safeRetryDelay = clampInt(retryDelaySeconds, EMAIL_AUTOMATION_RETRY_DELAY_SECONDS, 5, 86_400);
+  const stats = {
+    executed: true,
+    reason: 'ok',
+    claimed: 0,
+    sent: 0,
+    failed: 0,
+  };
+
+  for (let index = 0; index < safeMaxPerTick; index += 1) {
+    const task = await claimEmailOutboxTask();
+    if (!task) break;
+
+    stats.claimed += 1;
+
+    try {
+      const delivery = await sendEmailMessage({
+        to: task.recipient_email,
+        subject: task.subject,
+        text: task.text_body,
+        html: task.html_body,
+      });
+
+      await completeEmailOutboxTask(task.id, {
+        providerMessageId: delivery?.messageId || '',
+      });
+
+      stats.sent += 1;
+    } catch (error) {
+      stats.failed += 1;
+      await failEmailOutboxTask(task.id, {
+        error: error?.message || 'email_delivery_failed',
+        retryDelaySeconds: safeRetryDelay,
+      });
+
+      logger.warn('Falha ao entregar e-mail da fila.', {
+        action: 'email_automation_delivery_failed',
+        task_id: task.id,
+        recipient_email: task.recipient_email,
+        attempts: task.attempts,
+        error: error?.message,
+      });
+    }
+  }
+
+  if (stats.claimed > 0) {
+    await refreshQueueDepthMetrics().catch(() => null);
+  }
+
+  return stats;
+};
+
+const runLoopOnce = async () => {
+  if (stopping || inFlight) return;
+  inFlight = true;
+  let tickStats = null;
+
+  try {
+    tickStats = await runEmailAutomationTick();
+  } catch (error) {
+    logger.error('Falha no runtime de automação de e-mail.', {
+      action: 'email_automation_runtime_tick_failed',
+      error: error?.message,
+    });
+  } finally {
+    inFlight = false;
+  }
+
+  if (stopping || !started) return;
+
+  const claimed = Number(tickStats?.claimed || 0);
+  if (claimed > 0) {
+    nextDelayMs = EMAIL_AUTOMATION_POLL_INTERVAL_MS;
+  } else {
+    nextDelayMs = Math.min(EMAIL_AUTOMATION_IDLE_MAX_POLL_INTERVAL_MS, Math.max(EMAIL_AUTOMATION_POLL_INTERVAL_MS, Math.floor(nextDelayMs * EMAIL_AUTOMATION_IDLE_BACKOFF_MULTIPLIER)));
+  }
+
+  scheduleNextTick(nextDelayMs);
+};
+
+export const startEmailAutomationRuntime = () => {
+  if (started) return;
+
+  if (!EMAIL_AUTOMATION_ENABLED || !EMAIL_AUTOMATION_WORKER_ENABLED) {
+    logger.info('Runtime de automação de e-mail desabilitado.', {
+      action: 'email_automation_runtime_disabled',
+      automation_enabled: EMAIL_AUTOMATION_ENABLED,
+      worker_enabled: EMAIL_AUTOMATION_WORKER_ENABLED,
+    });
+    return;
+  }
+
+  if (!isEmailTransportConfigured()) {
+    logger.warn('Runtime de automação de e-mail não iniciado: SMTP não configurado.', {
+      action: 'email_automation_runtime_smtp_not_configured',
+    });
+    return;
+  }
+
+  started = true;
+  stopping = false;
+  inFlight = false;
+  nextDelayMs = EMAIL_AUTOMATION_POLL_INTERVAL_MS;
+
+  logger.info('Runtime de automação de e-mail iniciado.', {
+    action: 'email_automation_runtime_started',
+    poll_interval_ms: EMAIL_AUTOMATION_POLL_INTERVAL_MS,
+    idle_backoff_multiplier: EMAIL_AUTOMATION_IDLE_BACKOFF_MULTIPLIER,
+    idle_max_poll_interval_ms: EMAIL_AUTOMATION_IDLE_MAX_POLL_INTERVAL_MS,
+    max_per_tick: EMAIL_AUTOMATION_MAX_PER_TICK,
+    retry_delay_seconds: EMAIL_AUTOMATION_RETRY_DELAY_SECONDS,
+  });
+
+  void runLoopOnce();
+};
+
+export const stopEmailAutomationRuntime = () => {
+  if (!started && !timerHandle) return;
+  stopping = true;
+  started = false;
+  if (timerHandle) {
+    clearTimeout(timerHandle);
+    timerHandle = null;
+  }
+
+  logger.info('Runtime de automação de e-mail encerrado.', {
+    action: 'email_automation_runtime_stopped',
+  });
+};
+
+export const isEmailAutomationRuntimeEnabled = () => EMAIL_AUTOMATION_ENABLED && EMAIL_AUTOMATION_WORKER_ENABLED;
+export const isEmailAutomationRuntimeRunning = () => started && !stopping;

package/server/email/emailAutomationService.js

@@ -0,0 +1,125 @@
+import { enqueueEmailOutbox, getEmailOutboxStatusSnapshot } from './emailOutboxRepository.js';
+import { renderEmailTemplate } from './emailTemplateService.js';
+import { getEmailTransportMetadata } from './emailTransportService.js';
+
+const normalizeEmail = (value) =>
+  String(value || '')
+    .trim()
+    .toLowerCase()
+    .slice(0, 255);
+
+const normalizeOptionalText = (value, maxLength = 500_000) => {
+  const normalized =
+    String(value || '')
+      .trim()
+      .slice(0, maxLength) || '';
+  return normalized || null;
+};
+
+const normalizeTemplateKey = (value) =>
+  String(value || '')
+    .trim()
+    .toLowerCase()
+    .replace(/[^a-z0-9_:-]/g, '')
+    .slice(0, 64);
+
+const normalizePayloadObject = (value) => (value && typeof value === 'object' && !Array.isArray(value) ? value : {});
+
+const resolveEmailBodyFromPayload = ({ templateKey = '', templateData = {}, subject = '', text = '', html = '' } = {}) => {
+  const normalizedTemplateKey = normalizeTemplateKey(templateKey);
+  const normalizedTemplateData = normalizePayloadObject(templateData);
+
+  const renderedTemplate = normalizedTemplateKey ? renderEmailTemplate(normalizedTemplateKey, normalizedTemplateData) : null;
+
+  const normalizedSubject = normalizeOptionalText(subject, 180) || renderedTemplate?.subject || '';
+  const normalizedText = normalizeOptionalText(text, 120_000) || renderedTemplate?.text || null;
+  const normalizedHtml = normalizeOptionalText(html, 500_000) || renderedTemplate?.html || null;
+
+  if (!normalizedSubject) {
+    const error = new Error('Informe o assunto ou use um template válido.');
+    error.statusCode = 400;
+    throw error;
+  }
+
+  if (!normalizedText && !normalizedHtml) {
+    const error = new Error('Informe conteúdo de e-mail (text/html) ou use um template válido.');
+    error.statusCode = 400;
+    throw error;
+  }
+
+  return {
+    template_key: renderedTemplate?.template_key || normalizedTemplateKey || null,
+    template_payload: renderedTemplate ? normalizedTemplateData : {},
+    subject: normalizedSubject,
+    text_body: normalizedText,
+    html_body: normalizedHtml,
+  };
+};
+
+export const queueAutomatedEmail = async ({ to, name = '', templateKey = '', templateData = {}, subject = '', text = '', html = '', metadata = {}, priority = 50, scheduledAt = null, maxAttempts = 5, idempotencyKey = '' } = {}) => {
+  const normalizedEmail = normalizeEmail(to);
+  if (!normalizedEmail || !normalizedEmail.includes('@')) {
+    const error = new Error('Destinatário de e-mail inválido.');
+    error.statusCode = 400;
+    throw error;
+  }
+
+  const body = resolveEmailBodyFromPayload({
+    templateKey,
+    templateData,
+    subject,
+    text,
+    html,
+  });
+
+  const taskId = await enqueueEmailOutbox({
+    recipientEmail: normalizedEmail,
+    recipientName: normalizeOptionalText(name, 120),
+    subject: body.subject,
+    textBody: body.text_body,
+    htmlBody: body.html_body,
+    templateKey: body.template_key,
+    templatePayload: body.template_payload,
+    metadata: normalizePayloadObject(metadata),
+    priority,
+    scheduledAt,
+    maxAttempts,
+    idempotencyKey,
+  });
+
+  if (!taskId) {
+    const error = new Error('Não foi possível enfileirar o e-mail.');
+    error.statusCode = 500;
+    throw error;
+  }
+
+  return {
+    task_id: taskId,
+    recipient_email: normalizedEmail,
+    subject: body.subject,
+    template_key: body.template_key || null,
+  };
+};
+
+export const queueWelcomeEmail = async ({ to, name = '', loginUrl = '', redirectUrl = '', homeUrl = '', metadata = {}, idempotencyKey = '' } = {}) =>
+  queueAutomatedEmail({
+    to,
+    name,
+    templateKey: 'welcome',
+    templateData: {
+      name,
+      loginUrl,
+      redirectUrl,
+      homeUrl,
+    },
+    metadata,
+    idempotencyKey,
+  });
+
+export const getEmailAutomationStatusSnapshot = async () => {
+  const queue = await getEmailOutboxStatusSnapshot();
+  return {
+    queue,
+    transport: getEmailTransportMetadata(),
+  };
+};

package/server/email/emailOutboxRepository.js

@@ -0,0 +1,282 @@
+import { randomUUID } from 'node:crypto';
+
+import { executeQuery, TABLES } from '../../database/index.js';
+
+const STATUS_VALUES = new Set(['pending', 'processing', 'sent', 'failed']);
+
+const clampInt = (value, fallback, min, max) => {
+  const numeric = Number(value);
+  if (!Number.isFinite(numeric)) return fallback;
+  return Math.max(min, Math.min(max, Math.floor(numeric)));
+};
+
+const CLAIM_LOCK_TIMEOUT_SECONDS = clampInt(process.env.EMAIL_OUTBOX_LOCK_TIMEOUT_SECONDS, 15 * 60, 30, 24 * 60 * 60);
+
+const normalizeStatus = (value) => {
+  const normalized = String(value || '')
+    .trim()
+    .toLowerCase();
+  return STATUS_VALUES.has(normalized) ? normalized : null;
+};
+
+const normalizeEmail = (value) =>
+  String(value || '')
+    .trim()
+    .toLowerCase()
+    .slice(0, 255);
+
+const normalizeIdempotencyKey = (value) =>
+  String(value || '')
+    .trim()
+    .replace(/[^a-zA-Z0-9_:-]/g, '')
+    .slice(0, 180);
+
+const normalizeTemplateKey = (value) =>
+  String(value || '')
+    .trim()
+    .toLowerCase()
+    .replace(/[^a-z0-9_:-]/g, '')
+    .slice(0, 64);
+
+const normalizeSubject = (value) =>
+  String(value || '')
+    .trim()
+    .replace(/\s+/g, ' ')
+    .slice(0, 180);
+
+const normalizeNullableText = (value, maxLength = 200_000) => {
+  const normalized =
+    String(value || '')
+      .trim()
+      .slice(0, maxLength) || '';
+  return normalized || null;
+};
+
+const parseJson = (value, fallback = null) => {
+  if (value === null || value === undefined) return fallback;
+  if (typeof value === 'object') return value;
+  if (Buffer.isBuffer(value)) {
+    try {
+      return JSON.parse(value.toString('utf8'));
+    } catch {
+      return fallback;
+    }
+  }
+  if (typeof value === 'string') {
+    try {
+      return JSON.parse(value);
+    } catch {
+      return fallback;
+    }
+  }
+  return fallback;
+};
+
+const normalizeRow = (row) => {
+  if (!row) return null;
+  return {
+    id: Number(row.id),
+    recipient_email: normalizeEmail(row.recipient_email),
+    recipient_name:
+      String(row.recipient_name || '')
+        .trim()
+        .slice(0, 120) || null,
+    subject: normalizeSubject(row.subject),
+    text_body: row.text_body || null,
+    html_body: row.html_body || null,
+    template_key: normalizeTemplateKey(row.template_key) || null,
+    template_payload: parseJson(row.template_payload, {}),
+    metadata: parseJson(row.metadata, {}),
+    status: normalizeStatus(row.status) || 'pending',
+    priority: Number(row.priority || 0),
+    idempotency_key: row.idempotency_key || null,
+    available_at: row.available_at || null,
+    attempts: Number(row.attempts || 0),
+    max_attempts: Number(row.max_attempts || 0),
+    worker_token: row.worker_token || null,
+    provider_message_id: row.provider_message_id || null,
+    last_error: row.last_error || null,
+    locked_at: row.locked_at || null,
+    sent_at: row.sent_at || null,
+    created_at: row.created_at || null,
+    updated_at: row.updated_at || null,
+  };
+};
+
+export async function enqueueEmailOutbox({ recipientEmail, recipientName = '', subject, textBody = null, htmlBody = null, templateKey = '', templatePayload = {}, metadata = {}, priority = 50, scheduledAt = null, maxAttempts = 5, idempotencyKey = '' } = {}, connection = null) {
+  const normalizedRecipientEmail = normalizeEmail(recipientEmail);
+  const normalizedSubject = normalizeSubject(subject);
+  const normalizedTextBody = normalizeNullableText(textBody, 120_000);
+  const normalizedHtmlBody = normalizeNullableText(htmlBody, 500_000);
+
+  if (!normalizedRecipientEmail || !normalizedRecipientEmail.includes('@')) return null;
+  if (!normalizedSubject) return null;
+  if (!normalizedTextBody && !normalizedHtmlBody) return null;
+
+  const normalizedRecipientName =
+    String(recipientName || '')
+      .trim()
+      .slice(0, 120) || null;
+  const normalizedTemplateKey = normalizeTemplateKey(templateKey) || null;
+  const normalizedTemplatePayload = templatePayload && typeof templatePayload === 'object' && !Array.isArray(templatePayload) ? templatePayload : {};
+  const normalizedMetadata = metadata && typeof metadata === 'object' && !Array.isArray(metadata) ? metadata : {};
+  const safePriority = clampInt(priority, 50, 1, 100);
+  const safeMaxAttempts = clampInt(maxAttempts, 5, 1, 20);
+  const safeScheduledAt = scheduledAt ? new Date(scheduledAt) : null;
+  const scheduledValue = safeScheduledAt && Number.isFinite(safeScheduledAt.valueOf()) ? safeScheduledAt : null;
+  const normalizedIdempotencyKey = normalizeIdempotencyKey(idempotencyKey) || null;
+
+  const result = await executeQuery(
+    `INSERT INTO ${TABLES.EMAIL_OUTBOX}
+      (recipient_email, recipient_name, subject, text_body, html_body, template_key, template_payload, metadata, status, priority, idempotency_key, available_at, attempts, max_attempts)
+     VALUES (?, ?, ?, ?, ?, ?, ?, ?, 'pending', ?, ?, COALESCE(?, UTC_TIMESTAMP()), 0, ?)
+     ON DUPLICATE KEY UPDATE
+      id = LAST_INSERT_ID(id),
+      subject = IF(status IN ('pending', 'failed'), VALUES(subject), subject),
+      text_body = IF(status IN ('pending', 'failed'), VALUES(text_body), text_body),
+      html_body = IF(status IN ('pending', 'failed'), VALUES(html_body), html_body),
+      template_key = IF(status IN ('pending', 'failed'), VALUES(template_key), template_key),
+      template_payload = IF(status IN ('pending', 'failed'), VALUES(template_payload), template_payload),
+      metadata = IF(status IN ('pending', 'failed'), VALUES(metadata), metadata),
+      priority = GREATEST(priority, VALUES(priority)),
+      available_at = LEAST(available_at, VALUES(available_at)),
+      status = IF(status = 'failed' AND attempts < max_attempts, 'pending', status),
+      updated_at = UTC_TIMESTAMP()`,
+    [normalizedRecipientEmail, normalizedRecipientName, normalizedSubject, normalizedTextBody, normalizedHtmlBody, normalizedTemplateKey, JSON.stringify(normalizedTemplatePayload), JSON.stringify(normalizedMetadata), safePriority, normalizedIdempotencyKey, scheduledValue, safeMaxAttempts],
+    connection,
+  );
+
+  const insertedId = Number(result?.insertId || 0);
+  return Number.isFinite(insertedId) && insertedId > 0 ? insertedId : null;
+}
+
+export async function claimEmailOutboxTask({ allowRetryFailed = true } = {}, connection = null) {
+  const workerToken = randomUUID();
+  const statusClause = allowRetryFailed
+    ? `(status = 'pending'
+      OR (status = 'failed' AND attempts < max_attempts)
+      OR (status = 'processing' AND locked_at <= (UTC_TIMESTAMP() - INTERVAL ${CLAIM_LOCK_TIMEOUT_SECONDS} SECOND)))`
+    : `(status = 'pending'
+      OR (status = 'processing' AND locked_at <= (UTC_TIMESTAMP() - INTERVAL ${CLAIM_LOCK_TIMEOUT_SECONDS} SECOND)))`;
+
+  await executeQuery(
+    `UPDATE ${TABLES.EMAIL_OUTBOX}
+     SET status = 'processing',
+         worker_token = ?,
+         locked_at = UTC_TIMESTAMP(),
+         attempts = attempts + 1,
+         updated_at = UTC_TIMESTAMP()
+     WHERE id = (
+       SELECT id FROM (
+         SELECT id
+         FROM ${TABLES.EMAIL_OUTBOX}
+         WHERE ${statusClause}
+           AND available_at <= UTC_TIMESTAMP()
+         ORDER BY priority DESC, available_at ASC, id ASC
+         LIMIT 1
+       ) picked
+     )`,
+    [workerToken],
+    connection,
+  );
+
+  const rows = await executeQuery(
+    `SELECT *
+     FROM ${TABLES.EMAIL_OUTBOX}
+     WHERE worker_token = ?
+       AND status = 'processing'
+     ORDER BY id DESC
+     LIMIT 1`,
+    [workerToken],
+    connection,
+  );
+
+  return normalizeRow(rows?.[0] || null);
+}
+
+export async function completeEmailOutboxTask(taskId, { providerMessageId = '' } = {}, connection = null) {
+  if (!taskId) return false;
+  const normalizedProviderMessageId =
+    String(providerMessageId || '')
+      .trim()
+      .slice(0, 255) || null;
+
+  await executeQuery(
+    `UPDATE ${TABLES.EMAIL_OUTBOX}
+     SET status = 'sent',
+         provider_message_id = ?,
+         sent_at = UTC_TIMESTAMP(),
+         worker_token = NULL,
+         locked_at = NULL,
+         last_error = NULL,
+         updated_at = UTC_TIMESTAMP()
+     WHERE id = ?`,
+    [normalizedProviderMessageId, taskId],
+    connection,
+  );
+
+  return true;
+}
+
+export async function failEmailOutboxTask(taskId, { error = null, retryDelaySeconds = 0 } = {}, connection = null) {
+  if (!taskId) return false;
+
+  const safeDelay = clampInt(retryDelaySeconds, 0, 0, 86400 * 7);
+  const normalizedError =
+    String(error || '')
+      .trim()
+      .slice(0, 255) || null;
+
+  await executeQuery(
+    `UPDATE ${TABLES.EMAIL_OUTBOX}
+     SET status = IF(attempts >= max_attempts, 'failed', 'pending'),
+         worker_token = NULL,
+         locked_at = NULL,
+         last_error = ?,
+         available_at = IF(attempts >= max_attempts, available_at, UTC_TIMESTAMP() + INTERVAL ${safeDelay} SECOND),
+         updated_at = UTC_TIMESTAMP()
+     WHERE id = ?`,
+    [normalizedError, taskId],
+    connection,
+  );
+
+  return true;
+}
+
+export async function countEmailOutboxByStatus(status = 'pending', connection = null) {
+  const normalizedStatus = normalizeStatus(status);
+  if (!normalizedStatus) return 0;
+
+  const rows = await executeQuery(
+    `SELECT COUNT(*) AS total
+     FROM ${TABLES.EMAIL_OUTBOX}
+     WHERE status = ?`,
+    [normalizedStatus],
+    connection,
+  );
+
+  return Number(rows?.[0]?.total || 0);
+}
+
+export async function getEmailOutboxStatusSnapshot(connection = null) {
+  const rows = await executeQuery(
+    `SELECT
+      SUM(CASE WHEN status = 'pending' THEN 1 ELSE 0 END) AS pending,
+      SUM(CASE WHEN status = 'processing' THEN 1 ELSE 0 END) AS processing,
+      SUM(CASE WHEN status = 'sent' THEN 1 ELSE 0 END) AS sent,
+      SUM(CASE WHEN status = 'failed' THEN 1 ELSE 0 END) AS failed,
+      COUNT(*) AS total
+     FROM ${TABLES.EMAIL_OUTBOX}`,
+    [],
+    connection,
+  );
+
+  const row = rows?.[0] || {};
+  return {
+    pending: Number(row.pending || 0),
+    processing: Number(row.processing || 0),
+    sent: Number(row.sent || 0),
+    failed: Number(row.failed || 0),
+    total: Number(row.total || 0),
+  };
+}