Documentation Index
Fetch the complete documentation index at: https://mintlify.com/pewdiepie-archdaemon/odysseus/llms.txt
Use this file to discover all available pages before exploring further.
Odysseus includes a full IMAP/SMTP inbox with AI triage built in. It connects to email using standard IMAP for reading and SMTP for sending, authenticated with a username and password (or app password). This works with the overwhelming majority of email providers — any service that supports IMAP access and has not disabled password authentication can be added.
Adding an account
Open Email Settings
Go to Settings → Email → Add Account.
Fill in the account details
Enter a display name, then the IMAP and SMTP server details: hostname, port, TLS mode, username, and password.
Test the connection
Use the Test button to verify both IMAP and SMTP before saving. Odysseus will report which half (if either) failed.
Save
Once the test passes, save the account. Odysseus starts polling for new messages immediately. The first account you add becomes the default.
Provider compatibility
Gmail
Fastmail
iCloud Mail
ProtonMail
Self-hosted
Gmail requires IMAP to be enabled in your Google Account settings, and uses an App Password for third-party clients when 2-Step Verification is active (2FA is required to generate app passwords).
- Enable IMAP in Gmail settings → See all settings → Forwarding and POP/IMAP
- Generate an App Password: Google Account → Security → App passwords → Mail → Generate
| Setting | Value |
|---|
| IMAP host | imap.gmail.com |
| IMAP port | 993 (SSL/TLS) |
| SMTP host | smtp.gmail.com |
| SMTP port | 587 (STARTTLS) |
| Username | your full Gmail address |
| Password | the 16-character App Password |
Fastmail supports IMAP natively. Generate an app-specific password at Fastmail Settings → Privacy and Security → Connected Apps → New App Password.| Setting | Value |
|---|
| IMAP host | imap.fastmail.com |
| IMAP port | 993 (SSL/TLS) |
| SMTP host | smtp.fastmail.com |
| SMTP port | 587 (STARTTLS) |
| Username | your full Fastmail address |
| Password | app-specific password |
Apple iCloud Mail requires IMAP to be enabled in your iCloud account and uses an app-specific password.
- Enable iCloud Mail at iCloud.com → Account Settings
- Generate an app-specific password at appleid.apple.com → Sign-In and Security → App-Specific Passwords
| Setting | Value |
|---|
| IMAP host | imap.mail.me.com |
| IMAP port | 993 (SSL/TLS) |
| SMTP host | smtp.mail.me.com |
| SMTP port | 587 (STARTTLS) |
| Username | your Apple ID email address |
| Password | app-specific password |
ProtonMail uses end-to-end encryption and does not expose a standard IMAP endpoint directly. To use it with Odysseus you must run ProtonMail Bridge locally — it acts as a local IMAP/SMTP proxy that decrypts messages before passing them to the client.
- Install Proton Mail Bridge on the same machine running Odysseus.
- Sign in to Bridge and note the local hostname, ports, and generated Bridge password it displays.
- In Odysseus, enter those local credentials. Bridge typically listens on
127.0.0.1, port 1143 for IMAP and 1025 for SMTP.
For Docker installs, use host.docker.internal instead of 127.0.0.1 so Odysseus (inside the container) can reach Bridge (on the host). Any standard Dovecot/Postfix or compatible server works with standard credentials.| Setting | Typical value |
|---|
| IMAP host | your mail server hostname |
| IMAP port | 993 (SSL) or 143 (STARTTLS) |
| SMTP host | your mail server hostname |
| SMTP port | 587 (STARTTLS) or 465 (SSL) |
| Username | mailbox username or full address |
| Password | mailbox password |
Outlook and Office 365 limitation
Microsoft has disabled basic (username + password) authentication for Outlook and Microsoft 365 in most modern accounts and tenants. If you try to add an Outlook account, you will likely see:
IMAP: AUTHENTICATE failedSMTP: 535 5.7.139 Authentication unsuccessful, basic authentication is disabled
This is a Microsoft policy, not a configuration error. Odysseus does not support Microsoft OAuth or Graph Mail yet, so Outlook and Microsoft 365 accounts cannot currently be added through the IMAP/SMTP form. Use another email provider with app-password support, or track the future Microsoft Graph OAuth integration. AI triage features
Each account can have per-account AI triage enabled in Settings → Email. When active, Odysseus uses your configured utility or default model to process incoming messages in the background.
| Feature | What it does |
|---|
| Auto-summarize | Generates bullet-point summaries shown on hover in the inbox list. |
| Auto-reply draft | Drafts a reply in your writing style, pre-filled when you click Reply. |
| Auto-tag | Classifies messages with labels such as urgent, marketing, invoice, reminder, and spam. |
| Spam detection | Scores each message for spam probability; flagged messages appear under the spam tag filter. |
| Urgency scoring | Assigns an urgency score per message; the inbox unread dot changes color based on the highest-urgency unread. |
AI triage requires a working LLM endpoint. Set at least a Utility model in Settings → Models for background tasks. Triage runs in the background and does not block inbox loading.
CalDAV calendar sync
Calendar sync is configured separately from email. If your provider also offers CalDAV — for example Fastmail, Nextcloud, or a self-hosted Radicale server — connect your calendar in Settings → Calendar. See the Email and Calendar guide for the full CalDAV setup.
Credential storage
IMAP and SMTP credentials, including passwords and app passwords, are stored locally in data/ (encrypted at rest). Keep data/ private and exclude it from any backups you share or publish. It is gitignored by default — do not override that.