Credentials & Keychain
Where secrets live on macOS
Section titled “Where secrets live on macOS”IMAP/SMTP passwords and OAuth tokens that Primail stores are written
through KeychainCredentialStore into macOS Keychain Services.
The GUI process, primail, and primail-mcp on the same profile
are allowed to read those items. That is how mail fetch and send
work. Primail can read credentials it is authorized to use; do not
treat Keychain as a wall against the app itself.
Linux, Windows, and iOS Keychain/Credential Manager backends are
not implemented on this build. Those hosts error if they use
KeychainCredentialStore.
There is no production Primail Cloud ciphertext vault, no mandatory TOTP Primail account, and no “sign in on a new device and every mailbox appears” restore. Optional iCloud configuration sync is accepted future direction only.
What is not true
Section titled “What is not true”- “Even Primail cannot read your passwords.” The local processes that sync mail must read them.
- Factory reset via Settings → Privacy → Reset Primail…. That control is not in the Privacy panel.
- Settings → Primail Account → Change password for a Primail cloud login. That pane states vault sign-up and rotation are unavailable.
Rotating a mail-account password
Section titled “Rotating a mail-account password”- Change the password at the provider.
- Re-enter it when Primail shows the auth-failure banner, or use
CLI
primail account password-update ACCOUNT_ID(password on stdin) or MCPaccount_password_update. - Core verifies IMAP before replacing the Keychain item.
There is no cloud blob to push to other devices.
Google and Microsoft add-account flows exchange tokens in Core and store the refresh material in Keychain. Those token HTTP calls leave the device. Secrets are not returned on MCP/CLI account-add success payloads.
When Keychain is unavailable
Section titled “When Keychain is unavailable”macOS Keychain retrieval is a single get. If the item is locked, denied, missing, or otherwise unavailable, that call fails and Core reports an internal error. Fetch or send that needs the secret can fail. Unavailable Keychain access can prevent retrieval and may require OS authorization or a later retry.
Primail does not implement an automatic unlock, an indefinite wait, or a guaranteed later success. The OS may show its own authorization prompt; this page does not promise a specific dialog, and not every access waits.
Removing secrets
Section titled “Removing secrets”Remove an email account deletes that account’s Keychain entries after the local row is gone. Cleanup can be incomplete; the Settings summary says so. Uninstalling the app does not by itself guarantee Keychain leftovers are gone if removal never ran.