Skip to content

Getting Started

Jump to bottom
mrdulasolutions edited this page May 13, 2026 · 1 revision

Getting Started

This is the install guide for end users. If you want to build AOS Mail from source, see Building from Source.

Requirements

  • macOS 13 (Ventura) or later
  • Apple Silicon Mac (M1, M2, M3, M4 — any chip starting with "M")
  • An Anthropic API key OR an OpenRouter API key (free models work)
  • At least one email account: Gmail, iCloud, Fastmail, Outlook, Yahoo, or any IMAP/SMTP provider

Intel Macs: not currently supported. Intel binaries are on the roadmap but the GitHub macOS Intel runner pool has been unreliable — see the Roadmap page.

Install

  1. Open github.com/mrdulasolutions/AOS-Mail/releases/latest.
  2. Under "Assets", download AOS.Mail_<version>_aarch64.dmg (the file ending in .dmg).
  3. Double-click the downloaded .dmg to mount it.
  4. Drag AOS Mail into your Applications folder.
  5. Eject the DMG (right-click the disk icon in Finder → Eject), open Applications, double-click AOS Mail.

The app is signed by Apple Developer ID and notarized, so macOS Gatekeeper opens it directly — no "unidentified developer" warnings, no right-click + Open dance.

First-launch setup

On first launch you'll be walked through:

1. Connect your first email account

You'll see a chooser between:

  • Gmail — OAuth flow opens a browser, you sign in to Google, grant the permissions, and return to the app. Token is stored in macOS Keychain.
  • IMAP — presets for iCloud, Fastmail, Outlook/Office365, Yahoo, or Custom. Enter your email + an app-specific password (most providers require this — see the per-provider notes below).

Multiple accounts are supported. Add more anytime from Settings → Accounts → Add Account.

2. Paste an Anthropic or OpenRouter API key

The agent needs an LLM to talk to. Two options:

You can configure both and route different features to different models in Settings → Agent Tools → AI Models. You can also skip this step entirely on first launch and add the key later in Settings; the agent simply won't run until configured.

3. Let it sync

The initial sync downloads your last ~3 months of mail. For a Gmail inbox with ~10k messages, this typically takes 2–5 minutes. Subsequent syncs are incremental and nearly instant (Gmail History API, IMAP IDLE).

Per-provider notes

Gmail

Sign in with the Google account, grant the requested scopes (read/modify/send/labels). Tokens are stored in Keychain and per-account JSON. If revoke-and-reconnect is ever needed, Settings → Accounts → Remove, then re-add.

iCloud

You cannot use your regular Apple ID password — Apple requires an app-specific password.

  1. Sign in to https://account.apple.com.
  2. Sign-In and Security → App-Specific Passwords → +.
  3. Label it "AOS Mail" or similar.
  4. Copy the 16-character password (xxxx-xxxx-xxxx-xxxx).
  5. In AOS Mail's setup wizard, choose iCloud, paste your iCloud email + the app-specific password.

Fastmail

Generate an "app password" at https://app.fastmail.com/settings/security/devices. Use that with your Fastmail email.

Outlook / Office365

Requires app passwords (most accounts have this disabled by default — you may need to enable 2FA first). For corporate Office365, your admin may need to enable IMAP/SMTP at the tenant level.

Yahoo

Generate an app password at https://login.yahoo.com/account/security.

Custom IMAP

You need:

  • IMAP host + port (usually 993, SSL)
  • SMTP host + port (usually 465 SSL or 587 STARTTLS)
  • Username (usually your full email)
  • Password (provider-specific — often an app password)

Settings → Accounts → Add Account → Custom.

What to do first

Once mail has finished syncing:

  1. Open the Morning Briefing (icon at the top of the inbox) — see what the agent surfaced overnight.
  2. Hit the smart-action key (Space, by default) on the top thread — runs the agent's recommendation (archive, reply, snooze, etc.) with full undo.
  3. Generate a draft — click on a thread that needs a reply, click "Generate draft". The first one will feel generic; after the agent learns from your sent mail (~50+ sent messages), drafts start to sound like you.

Where things live

  • App data lives at ~/Library/Application Support/AOS Mail/ (database, OAuth tokens, preferences).
  • Logs at ~/Library/Application Support/AOS Mail/sidecar.log — useful when reporting bugs.
  • Keychain entries under "com.mrdulasolutions.aosmail" for API keys, OAuth refresh tokens, IMAP passwords.

To completely wipe AOS Mail's local state:

rm -rf ~/Library/Application\ Support/AOS\ Mail
security delete-generic-password -s com.mrdulasolutions.aosmail  # repeat per stored secret

(Or just drag AOS Mail to the Trash; the support directory persists across reinstalls.)

Updates

AOS Mail auto-updates. When a new version is published, the app checks in the background, downloads the update, and applies it on the next quit. You can also check manually in Settings → General → Updates → Check for Updates.

Auto-update requires that your installed version's embedded public key still matches the maintainer's current signing key. If we ever rotate the updater key (see Updater Keys and Signing), affected versions can't auto-update and have to be reinstalled manually once. We'll always announce this in release notes.

Home

Users

Developers

Issues · Releases · License

Clone this wiki locally