mailboxes

Monitored e-mail addresses read over IMAP, turning incoming mail into tickets without changing the domain MX.

Source path: libraries/sac/src/inbound

Module file: inbound.module.ts

Introduction

A mailbox binds an existing address to a SAC channel through an integration profile of provider `imap`. IMAP was chosen precisely because it requires no DNS change: the mailbox keeps working in Gmail, Outlook or on a phone while the system reads it.

A cron enqueues one poll job per mailbox whose interval has elapsed; the queue unique index on active `(type, source_entity_id)` doubles as the concurrency lock, so a slow poll never gets a second one stacked on top reading the same messages. The poll persists the raw message and uploads attachments, then a separate job interprets it — which means a bug in interpretation never loses a message that may already be gone from the server.

The read cursor is `last_seen_uid` plus `last_uid_validity`. When the server reassigns UIDs, `UIDVALIDITY` changes and the cursor restarts, because carrying the old one would silently skip everything that arrived since. Changing the folder resets the cursor for the same reason: IMAP UIDs are per folder.

The first read of a mailbox picks up only unread messages, so adopting a mailbox with history does not open a thousand retroactive tickets.

HTTP Endpoints

5 endpoints

Paginated list of monitored mailboxes, with channel and profile.

Query: page, pageSize, search

Body

Field	Type	Required	Notes
address	string (email)	yes	Also used to drop mail this system itself sent (loop guard)
channel_id	int	yes	—
integration_profile_id	int	yes	Must be a profile with the `imap` provider; the other e-mail providers only send
folder	string	no	Defaults to INBOX
poll_interval_seconds	int (>= 30)	no	—
strip_quoted_reply	boolean	no	Without it every reply brings the whole thread back
ignore_auto_submitted	boolean	no	—

Open a real IMAP connection and confirm the folder can be opened — which the profile-level test, always on INBOX, does not cover.

Params: id (int)

Read the mailbox now, without waiting for the cron interval.

Params: id (int)

Stop reading a mailbox. Tickets already opened from it are kept.

Params: id (int)