Accounts, Identities, and Collections

msgvault stores every source in one archive database: Gmail accounts, IMAP accounts, Microsoft 365 accounts, local imports, and chat/text imports. A source has an account identifier, optional display name, source type, labels, messages, attachments, and sync/import state.

As an archive grows it accumulates overlapping sources: a current Gmail sync, an old mbox export, Apple Mail from a retired laptop, IMAP backups, chat exports, SMS history. Three concepts keep that collection organized without losing any source's provenance.

The Data Model¶

msgvault introduces three concepts, always in the same order: account, then identity, then collection. Each one builds on the previous.

An account is one ingest source. A Gmail sync is one account. An mbox import is another. It is the smallest durable unit of provenance in the archive. If you import the same real-world mailbox twice, once through Gmail sync and once from an old mbox export, you get two accounts. msgvault never silently merges them, and it never infers that two imports belong together just because an address, display name, or message content overlaps.

An identity is the set of identifiers that mean "you" inside one account. These are the email addresses, phone numbers, chat handles, or synthetic identifiers for that source. Identity is per-account because the same address can mean different things in different imports: an address that is unambiguously you in one source may be misleading in another. A confirmed identity lets msgvault treat a message as "from you" within that account's context, which is what makes sent-copy detection work during deduplication.

A collection is a named group of accounts. The All collection exists by default and contains every account. You create others (work, personal, or any grouping you like) to search, report, and deduplicate a logical group without changing the underlying sources. A collection is the boundary for every cross-account operation. A collection's identity is the union of its member accounts' identities, computed at read time, so you never manage it directly. Collections contain accounts only, never other collections.

Deduplication operates over all three concepts and has its own Deduplication page.

OAuth Apps and Tokens¶

For personal Gmail accounts, a single client_secret.json supports all of them. Each add-account call authorizes one account and stores a separate token file.

Google Workspace organizations often restrict OAuth to apps created within their own org. If a Workspace account fails to authorize with your default app, create a separate OAuth app inside that org and add it as a named app in config.toml. See the OAuth Setup Guide for the full walkthrough.

Workspace admins can also use a Google service account with domain-wide delegation. Configure service_account_key under [oauth] or [oauth.apps.<name>], authorize the service account client in the Google Admin Console, then run msgvault add-account [email protected]. Service-account accounts do not store per-user refresh tokens; msgvault mints delegated tokens on demand.

Adding Accounts¶

# Gmail accounts (OAuth)
msgvault add-account [email protected]
msgvault add-account [email protected] --oauth-app acme   # Workspace org

# IMAP accounts (password)
msgvault add-imap --host imap.fastmail.com --username [email protected]

# Microsoft 365 / Outlook.com (OAuth2 over IMAP)
msgvault add-o365 [email protected]

Gmail accounts open a browser for OAuth authorization. IMAP accounts prompt for a password and test the connection. All accounts share the same archive database (SQLite by default, or PostgreSQL) and attachment storage.

Start by listing what msgvault already knows about. Every command in this guide takes the identifier from this list (typically the email address or source name):

msgvault list-accounts

Syncing¶

Sync all accounts at once by omitting the email argument:

# Full sync all accounts
msgvault sync-full

# Incremental sync all accounts
msgvault sync

Or sync a specific account:

msgvault sync-full [email protected]
msgvault sync [email protected]

If a token expires during sync, msgvault prints the re-authorization URL with the account name so you can select the correct Google account. It will not auto-launch a browser during re-auth to prevent accidentally authorizing the wrong account.

Identities¶

Each account has a confirmed "me" identity: the email addresses, phone numbers, chat handles, or synthetic identifiers that mean you inside that source. Deduplication uses this set for sent-copy detection, so for "sent" versus "received" to mean anything in older imports, msgvault needs to know which identifiers are you in each account.

Source identities are different from the observed people and durable profiles used by relationship exploration. See People, Profiles, and Source Identities for evidence discovery, bulk import, optional Fastmail alias inventory, person promotion, and typed attributes.

New Gmail, IMAP, Microsoft 365, MBOX, EMLX, WhatsApp, and Google Voice sources auto-confirm the source identifier by default. Use --no-default-identity on supported add/import commands when that is not correct. (iMessage imports are exempt, because iMessage contacts are not self-identifying.)

# List confirmed identifiers across all accounts
msgvault identity list

# Show one account's identity in detail, including which signals confirmed it
msgvault identity show [email protected]

# Add or remove identifiers manually
msgvault identity add [email protected] [email protected]
msgvault identity remove [email protected] [email protected]

Each confirmed identifier records the signals that confirmed it: account-identifier (the address matches the account's own identifier, such as the Gmail address itself), phone-e164 (a phone number from an SMS or chat source), manual (an entry you added via identity add), or config_migration (carried over from a legacy [identity] config block). An identifier accumulates signals over time as new evidence appears; it is removed only by identity remove.

identity list can be scoped to one account or one collection. A collection's identity is the union of its member accounts' confirmed identifiers:

msgvault identity list --account [email protected]
msgvault identity list --collection Work

Collections¶

Collections are named groups of accounts. The default All collection is created automatically and includes every account. User-created collections let you search, report, and deduplicate a logical group without changing the underlying sources.

# Create a collection from two accounts
msgvault collection create Work --accounts [email protected],[email protected]

# Inspect and edit membership
msgvault collection list
msgvault collection show Work
msgvault collection add Work --accounts [email protected]
msgvault collection remove Work --accounts [email protected]

# Delete only the collection record; sources and messages are untouched
msgvault collection delete Work

--accounts accepts account identifiers and numeric source IDs. One account can belong to multiple collections.

Scoped Search and Stats¶

Search queries run across all accounts by default:

msgvault search "quarterly report"

Use --account to limit results to a specific account, or --collection to limit results to all member accounts in a collection:

msgvault search "quarterly report" --account [email protected]
msgvault search "quarterly report" --collection Work
msgvault stats --collection Work

--account and --collection are mutually exclusive. If you pass a collection name to --account (or an account identifier to --collection), msgvault rejects it with a hint to use the other flag, so the two scopes never silently cross.

Deduplication¶

Once several accounts hold overlapping copies of the same message, deduplication collapses each set to one visible survivor while keeping every source's provenance intact. It hides redundant copies rather than deleting them, and every step beyond hiding is a separate, opt-in action. See the Deduplication page for the detection rules, survivor selection, and the reversible safety ladder.

TUI Filtering¶

Press A (uppercase) inside the TUI to open the account selector modal. Pick a single account to scope every view, or pick "All Accounts" to clear the filter. The currently selected account is shown in the title bar.

Meetings mode uses the same key for a separate source selector. It lists only configured Granola and Circleback sources, and changing it does not replace the Email account filter.

Command Reference¶

See the CLI Reference for the complete flag list on add-account, add-imap, add-o365, identity, and collection.