Mailboxes and the mirror

Every workflow, the webmail and the analyzer work from the mirror: a synchronised copy of each mailbox you connect. This page explains which mailboxes can be connected, what the mirror keeps and where, how it stays up to date, what to do when a mailbox stops syncing, and how actions decided by a workflow reach the real mailbox.

Mailboxes are managed on the Mailboxes page ("Connected mailboxes and the state of their mirror."). The accounts and accesses themselves are on the Connections page.

Providers you can connect

Provider	Shown as	How it connects	What it needs first
Google (Gmail, Google Workspace)	Gmail	OAuth: you sign in at Google and accept the requested access	an administrator has registered the organisation's Google application (Google)
Microsoft 365 (Outlook, Exchange Online), through Microsoft Graph	Microsoft 365	OAuth: you sign in at Microsoft and accept the requested access	an administrator has registered the organisation's Microsoft application (Microsoft)
Any IMAP/SMTP mailbox	IMAP	address, servers and password	nothing; the instance must have an encryption key to store the password (IMAP/SMTP)

A member can connect several mailboxes, of different providers. Each mailbox belongs to the member who connected it.

Access requested for mail. Google: read, send, modify and manage labels of Gmail (gmail.readonly, gmail.send, gmail.modify, gmail.labels). Microsoft: Mail.ReadWrite and Mail.Send. Access to files or calendars is requested separately, only when a member allows it for a node; connecting a mailbox gives no access to files.

Connecting a mailbox

Google or Microsoft

1. Open Mailboxes.
2. Under "Connect a mailbox", choose the provider and click "Connect a Google mailbox" or "Connect a Microsoft mailbox".
3. Sign in at the provider and accept the requested access.
4. You come back with the message "Mailbox {address} connected." and the mailbox starts syncing.

If the page shows "The OAuth application is not configured", an administrator must first register the organisation's application in Administration → OAuth applications.

IMAP/SMTP

1. Open Mailboxes and click "Connect an IMAP mailbox".
2. Fill in:

Field	Default	Notes
Mailbox address	—	the address that receives mail, not necessarily the login name
Incoming (IMAP): Server, Port	port 993
Outgoing (SMTP): Server, Port	port 465
Encrypted from the start (TLS)	ticked, for each server	unticked, the connection starts in clear and upgrades with STARTTLS — never in clear all the way
Login name (optional)	the address	only when your host gave you a different login name
Password	—	never shown again; prefer an "app password" when your provider offers one
Advanced → Accept a certificate the system does not validate	unticked	only for an internal server with a self-signed certificate

3. Click "Connect the mailbox". Your credentials are tried on a real IMAP connection, then on a real SMTP connection, before anything is saved: a wrong host, port, certificate or password is reported at once.

The usual ports are 993 (or 143 with STARTTLS) for IMAP, 465 (or 587 with STARTTLS) for SMTP. IMAP mailboxes connect with a password only.

Reconnecting an existing mailbox (same address), by OAuth or by the IMAP form, reactivates the same mailbox with its history: nothing is duplicated.

What the mirror stores, and where

For each mailbox, the mirror keeps every message of every folder or label — inbox, sent, drafts, archive, spam, trash and your own folders — with its threads, read and flagged state, and attachments.

What	Where
Message metadata: sender, recipients, subject, dates, snippet, folders and labels, read/flagged state, detected signals (auto-reply, mailing list, no-reply, sent by you)	database
Text used for search (the flattened body, up to 32,000 characters)	database
Threads, attachment metadata, folder list	database
The complete original message (.eml), each attachment, and the content of messages sent	object storage
The receiving log (what happened to each received message)	database

Object storage is an S3-compatible service set with the STORAGE_* variables (see Configuration). Without object storage configured, the instance keeps these files in memory only and loses them at restart: the webmail and workflows then fall back to the snippet stored in the database.

Folders and labels are recorded in the same vocabulary for every provider: INBOX, SENT, DRAFT, TRASH, SPAM, ARCHIVE, plus your own folders or labels. Gmail has labels rather than folders: an archived Gmail message is one that no longer has INBOX. Microsoft 365 well-known folders and IMAP special folders are mapped to the same names.

How synchronisation works

Each mailbox is kept up to date by several mechanisms working together:

Mechanism	Gmail	Microsoft 365	IMAP
Push — the provider signals a change within seconds	Google Pub/Sub notifications, when the instance is configured for them	Microsoft Graph change notifications	IMAP IDLE on the inbox
Polling — the instance asks "what changed since last time?"	every POLL_INTERVAL_SECONDS (300 s by default)	same	same
Delta — what is fetched	Gmail history since the last position	Graph delta per folder	changes per folder

• Push speeds things up; polling guarantees. Polling runs for every mailbox, whether push works or not, so a missed notification is caught up at the next poll. Push subscriptions are renewed automatically before they expire.
• Push needs instance settings. Gmail push needs GMAIL_PUBSUB_TOPIC and PUSH_SHARED_SECRET; Microsoft push needs PUSH_SHARED_SECRET and a public address. Without them, mailboxes sync by polling only. See Configuration.
• No message is read on your behalf. Syncing never marks a message as read at the provider.
• No duplicate. A message delivered by push and by polling is stored once.
• Click "Sync" on a mailbox card to ask for an immediate delta ("Sync requested."). If one is already pending, you see "A sync is already pending."

After an interruption (a long outage, a server stopped for a day), the provider may no longer be able to say what changed since the last position. The instance then catches up automatically on the period since the last successful sync, up to 24 hours back. For a longer gap, use Catch up on a period.

History imported at connection

When a mailbox is connected, the mirror imports its history in the background, most recent first: the last 7 days come first, so the mailbox is usable at once, then earlier periods in slices of BACKFILL_CHUNK_DAYS days (30 by default), down to BACKFILL_MONTHS months before the connection (12 by default). Both are instance settings; no choice is offered at connection.

The card shows the progress under "Backfill" (Pending, Running, Done, Failed) and "Backfilled down to" with the oldest date reached. The import resumes where it stopped after a restart, without duplicates.

History never starts workflows. Imported messages serve the webmail, search, the analyzer, the context given to AI and test runs, but only messages that arrive after the connection can trigger a workflow. Reconnecting a mailbox does not reset that point in time.

Which messages can start a workflow

A message reaches the workflow triggers only if it is:

1. new: delivered by synchronisation after the mailbox was connected — not imported history, not a catch-up, not a message already in the mirror;
2. not in Sent, Spam, Trash or Drafts;
3. in scope: not excluded by the organisation's or your own scope rules;
4. not stopped by a guardrail: a message produced by Mankomail itself (a send or a draft from a workflow or the webmail, coming back through sync), an automatic reply, a mailing-list or newsletter message, or a message from a no-reply address.

The messages you send yourself from your mail client land in Sent, and are therefore never considered (step 2).

Every message that passes steps 1 and 2 gets one line in the receiving log, with its outcome:

Outcome	Meaning
Excluded — organisation scope	the sender is excluded by the organisation's rules
Excluded — member scope	the sender is excluded by your rules
Excluded — guardrail	produced by Mankomail itself ("sent by self"), auto-reply, mailing list, or no-reply sender
Received, unmatched	in scope, but no trigger condition matched
Dispatched	at least one workflow started

The log is shown under Activity → Received, with the rule that decided ("Decided by"). An excluded message stays in the mirror and remains visible in the webmail: exclusion stops processing, not storage. How conditions are matched is described in Triggers and conditions.

Mailbox statuses

Status	Meaning	What to do
Active	the mailbox syncs	nothing
Error	the provider no longer accepts the access: token revoked, password changed, access withdrawn	reconnect the mailbox ("Reconnect this mailbox")
Disconnected	you disconnected it, or an administrator deactivated your account	reconnect it to resume

Only a refused access puts a mailbox in Error. Then:

• syncing stops and nothing arrives through this mailbox; a banner reads "1 mailbox is in error: {address} no longer receives anything.";
• you receive a notification "Mailbox {address} has stopped receiving";
• as soon as a sync succeeds again (after reconnecting), the mailbox returns to Active and you receive "Mailbox {address} is working again".

Other problems leave the mailbox Active and show under "Last error", with a "Technical detail" section (kind, code, provider message, operation, HTTP status):

Kind	Meaning
temporary error	the provider did not answer; the next sync retries on its own
permanent error on one message	for example a message deleted between two syncs; syncing continues
position expired	the interruption was too long for the provider to say where to resume; catch up on the missed period

When a mailbox has not synced for a while, its card shows "No sync for {duration}." A sync limited by the provider's quotas waits and resumes without counting as a failure.

Catching up on a period

"Catch up on a period…" replays synchronisation from a date you choose, to fill a gap after an interruption.

1. Open Mailboxes, and on the mailbox card choose "Catch up on a period…".
2. Pick the date under "Since". It can go back 92 days at most.
3. Click "Catch up". The card confirms "Catch-up requested from {date}."

What a catch-up guarantees:

• no duplicate: messages already in the mirror are neither duplicated nor downloaded again, so catching up on the same week twice only costs time;
• no workflow starts: a catch-up behaves like the history import — replaying three weeks does not send three weeks of automatic replies;
• one at a time per mailbox.

A mailbox must be Active to sync or catch up; otherwise reconnect it first. Through the API: POST /api/v1/mailboxes/:id/sync (immediate delta) and POST /api/v1/mailboxes/:id/resync with { "since": "<ISO 8601 date>" }. Both answer 202 { "enqueued": true | false }; refusals are 409 mailbox.not_active and 400 mailbox.resync_window_invalid (date in the future or more than 92 days back).

Disconnecting or deleting a mailbox

The actions menu of a mailbox card offers two different gestures. Before confirming, the dialog counts what is affected: messages, runs in progress, and the published workflows that trigger on this mailbox or send from it.

	Disconnect	Delete mailbox
Syncing	stops	stops
Stored access	removed: the IMAP password is erased; an OAuth account loses its mail access (it stays for files or calendars if you allowed them)	removed, the same way
Mirror (messages, threads, attachments, receiving log)	kept and readable in the webmail	erased, with the sending history and the runs that concerned this mailbox
Workflows triggering on it	stop triggering on this mailbox until you reconnect; they keep running on your other mailboxes	trigger only on your other mailboxes
Workflows sending from it	their sends fail until you reconnect	unpublished: choose another sending mailbox before publishing them again
Runs in progress	carry on; a send from this mailbox fails	erased
Reversible	yes: reconnecting resumes the same mailbox, history included	no
The mailbox at the provider	not touched	not touched

To delete, type the exact mailbox address in "To confirm, type the mailbox address", then click "Delete mailbox". Stored files are erased in the background by the hourly maintenance ("Its content will be erased from storage within the hour"); a very large mailbox can take a few hours.

Through the API: GET /api/v1/mailboxes/:id/removal-impact (what would be affected), POST /api/v1/mailboxes/:id/disconnect, and DELETE /api/v1/mailboxes/:id with { "confirm": "<mailbox address>" } (refused with 400 mailbox.confirmation_mismatch if the address does not match).

How workflows act on the real mailbox

When a workflow or the webmail sends, drafts, moves or flags a message, the action is not sent to the provider directly. It is first recorded as an outbound operation, then carried out by a background worker:

Operation	Produced by
send	Send in send mode, the webmail composer, approval requests
draft	Send in draft mode, the webmail
move, label	Move, the webmail
flag (read, flagged)	Flag, the webmail
delete (to the trash) and permanent deletion	the webmail; permanent deletion only where the provider allows it

What this guarantees:

• Never twice. Each operation carries a unique key: a step retried after a failure, or a double click, never sends a second email.
• Retries. A failed operation is retried, at most 5 attempts, waiting 30 seconds or the delay the provider asks for when it limits the rate.
• Sending limits. Sends wait their turn above SEND_MAX_PER_HOUR (100 per hour by default); they are not lost. Messages are limited to SEND_MAX_BYTES (25 MB by default).
• The send kill switch holds back send operations only: drafts, moves and flags keep working. See Governance.
• The mirror is not changed in advance. The new state comes back through the next sync, as for any change made at the provider. A message produced by Mankomail carries a mark of origin: when it comes back through sync, it never triggers a workflow.
• An access refused during an operation puts the mailbox in Error, as during a sync.

Retention

Data	Kept
Messages, bodies and attachments of a connected or disconnected mailbox	as long as the mailbox exists in Mankomail: never deleted by age
Receiving log	365 days
Finished live runs, their steps and data	180 days (see Runs)
Finished outbound operations and sending history	180 days
Test runs	7 days by default (SIMULATED_EXECUTIONS_RETENTION_DAYS)

The mirror of a mailbox disappears only when you delete the mailbox. Deleting a message in the webmail deletes it at the provider, and the change comes back to the mirror through sync.

Related pages

• Google, Microsoft, IMAP/SMTP
• Scope
• Triggers and conditions
• Configuration