Skip to main content

Tenant Mailbox

Audience: Engineering · Where in app: Your Mailbox card under Settings → Integrations → Messaging & email (MailboxCard.vue) · Since: 2026-10-16 (backend 35a5dd8dc, 34b7e7346; frontend 605109b6)

The tenant connects their own mailbox (SMTP + optional IMAP, app password) so lead-facing email goes out from their address: Agent K outreach (when routed there — see Agent K › Routing & the tenant mailbox), the visitor "resume your conversation" email, and Tapi can read it. Code: app/services/MailboxService.js (global mailbox), app/controllers/MailboxController.js, app/routes/mailboxRoutes.js, app/lib/mailboxRouting.js, app/jobs/MailboxReplyJob.js.

Data — company.mailbox​

A strict typed subdoc on CompanyModel — a new key must be added to the schema or writes drop silently. provider, email, from_name, username, password (SecretCrypto blob, Mixed, select: false — read with .select('+mailbox.password')), smtp_host/port/secure, imap_host/port/tls, use_for.{agent_k,visitor_emails} (default true), reply_to, bcc, daily_limit (default 100, API 1–2000), sent_day (UTC YYYY-MM-DD) + sent_count, track_replies (default true), reply_last_uid, last_reply_check_at, status (connected | error), last_error, connected_at, last_sent_at. Tapi: tapi.use_mailbox (read this mailbox instead of tapi.imap_*) and tapi.connection_error (was written but never schema'd, so it dropped).

Endpoints​

All passport; the company comes from GeneralHelper.resolveIntegrationCompany (shared with Tapi — a company outside the caller's agency is a 403, not a crash).

RouteWhat
POST /mailbox/connectValidate email, password, smtp_host; verify() (SMTP, and IMAP when a host is given) before saving; per-path $set so a reconnect keeps usage settings; reply_last_uid = IMAP uidNext − 1 so a reconnect never replays old mail
POST /mailbox/statusCard state, never the password: connected, can_read, use_for, daily_limit, sent_today, track_replies, agent_k_sends (ai_agent_k.enabled && route(company).sender === 'mailbox'), status, last_error, used_by_tapi
POST /mailbox/updateuse_for.*, from_name, reply_to, bcc, daily_limit, track_replies (no re-verify)
POST /mailbox/testSends "Your mailbox is connected" to the signed-in user (use: 'test' ignores use_for)
POST /mailbox/disconnect$set mailbox: {}
GET|POST /mailbox/unsubscribePublic. ?c&e&s HMAC (auth.token, mailbox-unsub:<c>:<email>, never expires). GET renders a button only (scanners prefetch); POST (button or RFC 8058 one-click) → addSuppression(reason 'unsubscribed', source 'unsubscribe_link') + dismisses that lead's drafted/sending actions

Send path​

MailboxService.send(company_id, mailOptions, { use, broadcast_id }):

  • Returns null when there's no usable mailbox (no creds, undecryptable, status: 'error', or use_for[use] === false) — the caller decides the fallback.
  • From = { from_name || caller's name, mailbox email }; adds replyTo / bcc.
  • _reserveSend atomically takes a slot from the UTC-day allowance; over the limit throws MAILBOX_DAILY_LIMIT ("Your mailbox's daily limit of N emails is reached"). A send that never reached the server gives its slot back.
  • An auth failure (EAUTH / 535 / 534) parks the mailbox in status: 'error' with friendlyError(err) until reconnect; the card shows Mailbox problem.
  • Logging (34b7e7346) — send writes its own email_logs row (sent / failed with full SMTP diagnostics via shared lib/mailError.js / daily-limit refusal), tagged company_id (index {company_id, created_at}), so Agent K sends and test sends are logged; MailService no longer logs mailbox sends (no duplicates). A failed log write never fails the send.

Callers:

  • MailService — send_as_company: '<use>' (only lead-facing mail; today ChatTranscriptEmailJob → visitor_emails, also carried through EmailQueueService) tries the mailbox first and falls back to platform mail on null or error.
  • Agent K — NoxGhlActionService._sendViaMailbox with use: 'agent_k'; never falls back (see the Agent K page for threading/unsubscribe).

Reply & bounce polling​

MailboxReplyJob (schedular, every 5 min) picks companies with mailbox.email, imap_host, track_replies ≠ false, status ≠ error and runs pollReplies: INBOX UIDs above reply_last_uid since last_reply_check_at − 24h, max 200 per pass. Own address skipped; mailer-daemon/postmaster → Final-Recipient → suppress bounced + dismiss open drafts (only if that address is an Agent K mailbox lead); otherwise only senders matching mailboxRouting.leadQuery (an mbx_ lead, or context.send_via: 'mailbox' + context.person.email, case-insensitive) reach handleInboundReply with the message-id (used to thread the next touch). The watermark advances past handled messages even when the pass fails. leadQuery is an unindexed regex scoped by company_id — index it if mailboxes get big.

Frontend​

components/integrations/MailboxCard.vue (status, Used for, Sent today, Configure / Send test / Reconnect / Disconnect via ConfirmDialog), MailboxModal.vue (connect; vee-validate + zod), MailboxSettingsModal.vue (usage switches, sender, reply-to, BCC, daily limit, reply tracking), mailboxPresets.js (Gmail, Outlook/M365, Yahoo, iCloud, Zoho, Custom hosts + app-password steps; shared with TapiModal.vue, which offers Use my connected mailbox when it can read). Agent K's Outreach tab reads company.mailbox off the cached company (mailboxReady), so the card reloads /user/me after changes.

Deploy​

  • SECRET_ENCRYPTION_KEY must be identical in backend and schedular secrets (Agent K sends + MailboxReplyJob run in the schedular). Schedular secret.sops.yaml got the key 2026-10-16; a mismatch logs password can't be decrypted — SECRET_ENCRYPTION_KEY differs? and every send returns null. Restart the schedular after flux applies.
  • Microsoft 365 turns SMTP app passwords off by default from end of December 2026 (preset copy warns tenants).