Skip to main content

Adding an Email Account

MailCopilot supports any email provider that uses standard IMAP and SMTP protocols. You can also sign in with Google or with a Microsoft 365 / Outlook.com account using OAuth for a seamless experience.

Adding via the Setup Wizard​

When you click Connect email (the mail icon at the bottom of the sidebar) or open the account manager, you will see the setup wizard.

Step 1: Choose Your Provider​

The wizard now starts with an explicit provider picker -- you tell MailCopilot which provider you use before entering any credentials. Each provider is shown as a card with its provider logo or icon:

  • Gmail -- jumps straight into the Google OAuth flow. A browser window opens where you authorize MailCopilot to access your Gmail account; no password entry is needed.
  • Outlook / Microsoft 365 -- jumps into the Microsoft OAuth flow (Authorization Code with PKCE) and connects via Microsoft Graph. Works for personal @outlook.com / @hotmail.com / @live.com accounts as well as Microsoft 365 work and school accounts.
  • Generic IMAP/SMTP -- for any other provider (Yahoo, Fastmail, Yandex, Mail.ru, ProtonMail Bridge, your company mail, self-hosted servers, and so on). Advances to a confirmation step that exposes a single IMAP/SMTP account button, which then opens the credential-entry form.

You can move between cards with the arrow keys and confirm the selection with Enter or Space. After picking a provider, the wizard proceeds with the steps appropriate for that provider. On Generic IMAP/SMTP, the Back button on the confirmation step returns to the provider picker; the credential-entry step also has a Back button, and it returns to the confirmation step (one step at a time). The server-detection and manual-configuration steps move forward only — to start over with a different provider, cancel the wizard and reopen it.

If you ever want to use Outlook over Generic IMAP/SMTP instead of OAuth, you can pick the Generic card and connect with an app password against outlook.office365.com / smtp.office365.com.

Step 2: Enter Your Credentials (Generic IMAP/SMTP)​

If you chose Generic IMAP/SMTP:

  1. Enter your email address and password.
  2. Optionally enter a display name (the name shown in outgoing messages).
  3. Optionally enter an email address (From) -- this is the address used in the "From" field of outgoing messages. If left blank, the SMTP login address is used.
  4. If your SMTP credentials are different from your IMAP credentials, check "SMTP login/password is different" and enter them separately.
  5. Click Next.

Step 3: Server Detection​

MailCopilot will attempt to automatically detect your mail server settings using standard autodiscovery protocols. If successful, the detected IMAP and SMTP servers are shown in editable fields. You can review and adjust the display name, email address, server hosts, ports, and SSL settings before connecting.

  • Click Connect to test the connection and save the account.
  • If you want full manual control over all settings (including separate IMAP/SMTP credentials), click Manual setup.

Manual Configuration​

If automatic detection did not find your server, or if you need to customize the settings:

  • IMAP: enter the host, port (typically 993), and check SSL/TLS.
  • SMTP: enter the host, port (typically 465 or 587), and check SSL/TLS.
  • Use the Autoconfigure button to try automatic detection again.
  • Use the Test connection button to verify your settings before saving.

Google Account (OAuth)​

Pick the Gmail card in the wizard. A browser window will open where you can authorize MailCopilot. Once authorized, the account is added automatically with the correct IMAP and SMTP settings.

Microsoft 365 / Outlook Account (OAuth)​

Pick the Outlook / Microsoft 365 card in the wizard. A browser window will open at the Microsoft sign-in page; sign in with your @outlook.com, @hotmail.com, @live.com, or work/school account and approve the requested permissions. The bundled Microsoft client uses the Authorization Code flow with PKCE without a client secret -- no client secret leaves your device. Custom builds that override the bundled client by setting both MAILCOPILOT_MS_CLIENT_ID (a custom Azure app registration) and MAILCOPILOT_MS_CLIENT_SECRET (intended for tenants that issued a confidential client) do send that secret to Microsoft's token endpoint over TLS. MAILCOPILOT_MS_CLIENT_SECRET on its own (without a custom client ID) is ignored. Once authorized, the account is added automatically.

For sending mail, MailCopilot uses Microsoft Graph (POST /me/sendMail) on Outlook accounts because Microsoft has disabled SMTP AUTH on most personal Outlook.com accounts created since 2024. The Graph send path is unaffected by that policy. Sent messages are saved to your Sent folder by Microsoft automatically.

If your Outlook account stops working after a long offline period, the OAuth refresh token may have expired. Open Settings > Accounts, edit the account, and use the Microsoft re-authentication button to sign in again.

TLS Certificate Verification​

MailCopilot always verifies TLS certificates when connecting to mail servers. If your server uses a custom or self-signed certificate, a trust prompt will appear during the connection test. You can review the certificate details and choose to trust it.

When signing in with Google, if your network uses a proxy or antivirus that replaces TLS certificates, MailCopilot will detect this and automatically offer to trust the certificate. You will see the certificate details (host, issuer, fingerprint) and can choose to accept or decline. The account is saved regardless, and you can manage certificate pins later in the account settings.

Managing Multiple Accounts​

You can add as many accounts as you need. To switch between accounts, use the sidebar or go to Settings > Accounts. The active account is highlighted, and you can set any account as the current one.

Customizing Account Avatar​

Each account is displayed in the sidebar with an avatar -- a colored circle with initials. You can personalize the avatar in Settings > Accounts by clicking the palette icon next to the account.

Display modes​

  • Letters -- a colored circle with 1--2 characters (initials). You can enter custom initials if the automatic ones are not ideal (for example, when all accounts have the same display name).
  • Icon -- a colored circle with an icon from a preset collection (mail, briefcase, star, rocket, etc.).
  • Gravatar -- loads your profile picture from Gravatar based on your email address. If no Gravatar is found, the avatar falls back to letters.

Changing the color​

Click any color in the palette to change the avatar background. The color is saved and stays the same across restarts.

Tooltip​

When you hover over an account avatar in the sidebar, a tooltip shows the account name and email address.

Supported Providers​

MailCopilot works with any IMAP/SMTP-compatible provider, including:

  • Gmail (via OAuth or app password)
  • Outlook / Microsoft 365
  • Yahoo Mail
  • Fastmail
  • Yandex Mail
  • Mail.ru
  • ProtonMail (via ProtonMail Bridge)
  • Self-hosted servers (Dovecot, Postfix, Zimbra, etc.)