Skip to main content
Suchi can poll multiple IMAP mailboxes. Each message is stored as an EML document, attachments become child documents, and normal extraction, filing, and automation behavior follows. Each mailbox belongs to an immutable filing system and has its own owner, credentials, folder, poll interval, filters, cursor and health state. A failing mailbox does not stop other pollers. Select the destination system before adding an account; the owner must be active and able to enter it. Messages and attachment children, including files-only intake, inherit that system. Duplicate matching is owner-and-system scoped. Membership remains an additional gate to the existing owner/admin mailbox rules.

​
Provider setup

Provider presets fill host, port, TLS, and default authentication. They do not bypass provider account policy.

​
Microsoft and Outlook

Pick Microsoft and click Sign in with Microsoft. Published builds use Suchi’s public-client registration, so ordinary users need no Azure account, client ID, or secret. A deployment operator may set a different public-client ID in the config file or environment before starting Suchi. See Microsoft mailbox sign-in.

​
Gmail

v0.1 uses an app password, not the normal Google Account password or Google OAuth:
  1. Enable 2-Step Verification.
  2. Create a value under Google App Passwords.
  3. Use the full Gmail address and the generated 16-character password.
Workspace policy, Advanced Protection, or security-key-only verification may disable app passwords. Suchi cannot connect those Gmail accounts in v0.1.

​
iCloud Mail

v0.1 uses an app-specific password, not the normal Apple Account password:
  1. Turn on two-factor authentication for the Apple Account.
  2. Open Apple Account and create an app-specific password for Suchi under Sign-In and Security > App-Specific Passwords.
  3. Use the part before @icloud.com as the username and paste the generated password into Suchi.
If that username is rejected, try the full iCloud Mail address. Changing the Apple Account password revokes all app-specific passwords. See Apple’s app-specific password instructions.

​
Fastmail and Zoho

  • Fastmail: create an app password under Settings > Privacy & Security > Integrations. The account plan must include IMAP.
  • Zoho: enable IMAP and use an application-specific password when account policy requires it. Some organizations and regions use a host other than imap.zoho.com; copy the server shown in Zoho settings.

​
Proton Bridge and custom IMAP

Proton Mail requires Bridge on a trusted machine or container network. Use the Bridge-generated username and password, and configure its local host, port, TLS, and CA settings in Suchi. For Yahoo, Dovecot, mailcow, or another provider, choose Custom and use its incoming IMAP values. Prefer TLS on port 993 and a provider-scoped app password. Suchi reads mail only and needs no SMTP configuration.

​
Add a mailbox

  1. Administrators open Settings > Archive configuration > Email intake. Members with Manage mailboxes open Settings > My account > Mailboxes. Select Add mailbox.
  2. Choose the provider, display name, and mailbox username. Administrators also choose the document owner; a member always owns their own mailbox.
  3. Enter an app password or complete Microsoft sign-in.
  4. Add one or more intake rules for the messages to accept and choose whether each rule keeps the email and its files or files only.
  5. Choose whether accepted messages stay unchanged, are marked read, or move to another folder.
  6. Under Advanced, set Sync mail from. New accounts default to the current time so adding a mailbox does not import years of history unexpectedly.
  7. Save, then run Test connection. Use Preview matches while editing to check the policy against recent, unchecked messages.
The supervisor starts or reloads the mailbox within seconds. Adding, editing, disabling, deleting, testing, signing in, or changing mailbox credentials does not require a Suchi restart. Removing an owner’s mailboxes capability atomically disables their mailbox rows with the user change, then reloads the supervisor after commit. See capability revocation for regrant behavior. Disabling an account discards its pending Microsoft sign-ins only after the account change commits; a rejected disable does not discard them. Renaming a mailbox also updates its display name on linked document sources. The address and folder remain the values observed at ingest. Deleting the mailbox does not delete provenance; document details fall back to its recorded name. The poll interval is per mailbox, from 1 to 1440 minutes. A mailbox whose owner is disabled is not polled. Custom CA files are validated when a mailbox is created, changed, enabled, or tested; a missing or invalid CA is rejected before the poller uses it. Suchi selects authentication from the provider: Microsoft always uses OAuth; the other presets use their app-specific or Bridge password. Custom IMAP uses password authentication. There is no separate authentication-mode switch.

​
History and cursor behavior

sync_since is an absolute initial-history floor expressed as Unix seconds. Set it to an earlier time to backfill or to zero to allow all history. The date applies to the configured source folder; intake rules still decide which messages are archived. Changing the date resets the UID cursor to rescan that history. Already archived messages are deduplicated. Mail is downloaded in batches of at most 50 messages. Each completed batch saves its UID cursor, so a later failure resumes from that batch’s checkpoint rather than downloading the whole history again. Logs report emailwatch.batch_completed with the batch count and cursor. Accepted documents appear as they are imported; they do not wait for the entire history to finish. If a message fails, the cursor does not advance past it. Deduplication uses Message-ID per system and owner, including messages that also arrive through a watched folder or mbsync in that same system. Another system gets a distinct document. Test connection checks connectivity and authentication, not folder search or message downloads. A successful test does not clear a sync failure or update the last successful sync time; only a successful polling cycle does that. The amber never synced state means no successful cycle has been recorded, while a red error state reports the last failure. Reload the mailbox list to see updated polling status. Changing connection or source-folder settings resets that mailbox’s UID cursor so a cursor from the old source is not reused against the new one. Deleting or moving a message in the provider while Suchi is polling is harmless. Suchi skips a message that disappears between mailbox discovery and download; it does not mark the mailbox unhealthy or remove an already archived document. Raw messages are bounded before parsing at roughly twice SUCHI_EMAIL_MAX_ATTACH plus 8 KiB. An oversized message is skipped, recorded as document.ingest.skipped in the audit log, and treated as consumed so it cannot permanently block the mailbox cursor. Without a processed folder, Suchi leaves server read state unchanged unless Mark messages as read is enabled.

​
Intake policy and automations

Each mailbox has 1 to 20 intake rules. A rule accepts every message, messages with files, or messages matching its filled sender, recipient, subject, and filename conditions. Rules are alternatives (OR), while conditions inside one matching rule are combined with AND. Comma-separated values inside one condition are alternatives. Sender and recipient entries accept full addresses or @domain suffixes. Filename entries are globs such as *.pdf or invoice-*. Matching fields are stacked at full width and start at the same single-line height. Drag the bottom-right corner of any field to resize it vertically when editing longer comma-separated lists. Each rule can retain both the email and its files or files only. When a message matches multiple rules with different choices, Suchi retains the email and its files. For example, use one files-only rule for messages with attachments and a second email-and-files rule for subjects containing distribution advice. A message rejected by every rule never enters the archive, Automations, or document history and is left untouched on the mail server. Preview reads only envelope metadata and attachment filenames for at most 25 recent messages and returns at most five matching samples. Consumption automations can filter on sender, subject, source folder, and attachment presence. Use them to assign correspondents, tags, document types, filing categories, or storage paths. See Automations.

​
Alternative mbsync path

Use mbsync when you need a local Maildir mirror, already run mbsync, or want Suchi to receive files without storing mailbox credentials. The built-in poller is the simpler default.

​
Troubleshooting

  • Microsoft sign-in fails: confirm IMAP access is enabled for the mailbox, then retry Sign in with Microsoft and review any tenant consent policy.
  • Microsoft sign-in unavailable: remove an invalid configured client ID to restore Suchi’s shipped registration on the next start.
  • Gmail requests an application password: enable 2-Step Verification and use a Google app password. There is no Google OAuth fallback in v0.1.
  • Provider rejects credentials: verify that the credential is an app password and the plan or organization allows IMAP.
  • Messages missing: inspect Sync mail from, the intake policy, source folder, and the mailbox row’s last error. Preview the policy before saving it.
  • Changes seem ignored: wait a few seconds for supervisor reconciliation, then inspect emailwatch.supervisor logs. Do not restart Suchi.
Provider references: Google IMAP, Fastmail IMAP, Apple Mail settings, Zoho IMAP, and Proton Bridge.