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).
| Route | What |
|---|---|
POST /mailbox/connect | Validate 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/status | Card 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/update | use_for.*, from_name, reply_to, bcc, daily_limit, track_replies (no re-verify) |
POST /mailbox/test | Sends "Your mailbox is connected" to the signed-in user (use: 'test' ignores use_for) |
POST /mailbox/disconnect | $set mailbox: {} |
GET|POST /mailbox/unsubscribe | Public. ?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', oruse_for[use] === false) — the caller decides the fallback. - From =
{ from_name || caller's name, mailbox email }; addsreplyTo/bcc. _reserveSendatomically takes a slot from the UTC-day allowance; over the limit throwsMAILBOX_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 instatus: 'error'withfriendlyError(err)until reconnect; the card shows Mailbox problem. - Logging (
34b7e7346) —sendwrites its ownemail_logsrow (sent / failed with full SMTP diagnostics via sharedlib/mailError.js/ daily-limit refusal), taggedcompany_id(index{company_id, created_at}), so Agent K sends and test sends are logged;MailServiceno longer logs mailbox sends (no duplicates). A failed log write never fails the send.
Callers:
- MailService —
send_as_company: '<use>'(only lead-facing mail; todayChatTranscriptEmailJob→visitor_emails, also carried throughEmailQueueService) tries the mailbox first and falls back to platform mail on null or error. - Agent K —
NoxGhlActionService._sendViaMailboxwithuse: '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_KEYmust be identical in backend and schedular secrets (Agent K sends +MailboxReplyJobrun in the schedular). Schedularsecret.sops.yamlgot the key 2026-10-16; a mismatch logspassword 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).