Connections
A connection is how Mailgestor reaches a mailbox. It holds a credential the provider issued, encrypted under a key unique to your account, and lists the mailboxes that credential can read. Jobs are created over a connection.
The three kinds
| Kind | Who sets it up | What it covers | What is asked of you |
|---|---|---|---|
| Gmail account | The mailbox's owner | That one mailbox | Sign in to Google and allow read-only access |
| Google Workspace organisation | A Workspace super administrator | Every mailbox in the directory | Authorise a client ID in the Admin console, then sign in as the administrator |
| Microsoft 365 organisation | A Microsoft 365 global administrator | Every user with a mailbox | Grant admin consent, then sign in to the same tenant |
The administrator steps for the two organisation kinds are on their own pages: Google Workspace and Microsoft 365.
What a connection can read
Mail, calendar events and contacts, read-only. For a Gmail account, Google asks for exactly those three read scopes and nothing else. For an organisation, the same three plus the directory, so Mailgestor can list mailboxes.
Mailgestor never writes to the mailbox. It cannot send, move, label or delete.
The Connections page
Every connection shows its kind, when it was added, when it was last checked, its mailboxes, and a health state:
- Healthy: the last check reached the provider.
- Unknown: not checked yet.
- Failing: the last check failed for a reason other than access being withdrawn; the message says what happened. Provider problems during a run do not change this; they show on the job.
- Revoked: the provider refused the credential. Someone removed the app's access, the password changed, or the consent expired. Connect again.
The menu on each connection offers:
- Archive: start a new job on this connection.
- Discover mailboxes (organisations): re-read the directory. New accounts appear; accounts that have gone are marked. Jobs also do this every run.
- Test connection: ask the provider for the mailbox list now, to prove the credential still works.
- Authenticate again: go through the provider's consent or sign-in once more for this connection, keeping its mailboxes and archives. Use it when the connection shows Revoked, when a provider registration changes and an organisation must consent again, or when a Gmail owner changed their password. For a Workspace it opens the sign-in as the administrator the connection was attached with; for a Microsoft 365 organisation it runs the two consent screens again.
- Remove: delete the credential. Mailboxes archived through it stay until their own retention ends. A connection with jobs that are not finished cannot be removed.
Connections that go unused
A connection that has not run a job for six months has its credential removed, so a forgotten grant cannot linger. It shows as Revoked with a note saying why, its archives are unaffected, and the account's owners are emailed. Connect it again from the Connections page to use it.
One organisation, one account
A Google Workspace domain or a Microsoft 365 tenant can be attached to one Mailgestor account only. If another account already holds it, the attach is refused with a message saying so. Remove it from the first account to move it.
Mailbox identity
Mailboxes are identified by the provider's account id, not the address. If a leaver's address is given to a newcomer, that is a new mailbox with its own archive. If an account is removed from the directory and later restored with the same id, it is the same mailbox again.