Swanmail

Accounts ​

Swanmail supports multiple account types. Accounts are stored locally in SQLite; credentials are encrypted with a key kept in the data directory on macOS, protected by Windows' DPAPI, or kept in the Linux Secret Service (see Privacy).

OAuth credentials ​

Gmail and Outlook / Microsoft 365 use OAuth 2.0. The sign-in page opens in your web browser and returns to Swanmail on a local address.

Built-in clients. A release build comes with its own Google and Microsoft clients, so Continue with Google and Continue with Microsoft work with no setup — for personal Microsoft accounts (Outlook.com, Hotmail, Live) as well as work and school ones. Yahoo and Fastmail have no OAuth sign-in: add those accounts with an app password or API token.

Override. Advanced users and developers can replace the built-in clients with their own at runtime in one of two ways:

  1. A config.json file in Swanmail's data directory.
  2. Environment variables in the environment Swanmail is started from: SWANMAIL_GMAIL_CLIENT_ID, SWANMAIL_GMAIL_CLIENT_SECRET, SWANMAIL_OUTLOOK_CLIENT_ID, SWANMAIL_OUTLOOK_TENANT_ID.

Each value is looked up in config.json first, then the environment, then the built-in value. The Microsoft tenant defaults to common.

A sign-in button appears only when its provider's client is configured: Continue with Google needs both the client ID and the secret, Continue with Microsoft the client ID. Without one the button could only fail, so the dialog shows the manual form instead.

There is currently no in-app form for entering OAuth credentials. This is intentional: registering an OAuth app and copying client IDs is an advanced/power-user task, and exposing it in the main UI tends to confuse users who just want to sign in.

config.json ​

Create or edit config.json in Swanmail's data directory:

  • macOS: ~/Library/Application Support/swanmail/config.json
  • Windows: %APPDATA%\swanmail\config.json
  • Linux: ~/.config/swanmail/config.json (or under $XDG_CONFIG_HOME)

The SWANMAIL_DATA environment variable moves the whole directory.

Example:

json
{
  "gmailClientId": "your-gmail-client-id",
  "gmailClientSecret": "your-gmail-client-secret",
  "outlookClientId": "your-outlook-client-id",
  "outlookTenantId": "common"
}

Restart the app after editing the file.

For local development ​

A build from source takes its built-in Google and Microsoft clients from a git-ignored .env.local at the project root:

bash
SWANMAIL_GMAIL_CLIENT_ID=your-gmail-client-id
SWANMAIL_GMAIL_CLIENT_SECRET=your-gmail-client-secret
SWANMAIL_OUTLOOK_CLIENT_ID=your-outlook-client-id

pnpm dev runs the backend without a build step that reads it, so for pnpm dev export the same variables in the shell that runs it, or put them in config.json in the development profile (.dev-profile/).

Gmail ​

A release build signs in to Gmail out of the box: choose Continue with Google under Settings → Accounts → Add Account. To use a Google client of your own instead:

  1. Create a project in Google Cloud Console.
  2. Enable the Gmail API.
  3. Create OAuth 2.0 credentials with type Desktop app.
  4. Put the client ID and secret in config.json (gmailClientId, gmailClientSecret) as shown above.
  5. In Swanmail, go to Settings → Accounts → Add Account and choose Continue with Google, then complete the sign-in flow.

Outlook / Microsoft 365 ​

A release build signs in to Microsoft out of the box, for personal accounts (Outlook.com, Hotmail, Live) and for work or school accounts alike: choose Continue with Microsoft under Settings → Accounts → Add Account. Your organization may still require an administrator to approve the app. To use an app registration of your own instead:

  1. Register an app in the Microsoft Entra admin center → App registrations, for accounts in any organizational directory and personal Microsoft accounts.
  2. Add a redirect URI of type Public client/native (mobile & desktop): http://localhost. Swanmail listens on a random port for the callback; the port is not part of the match. There is no client secret. Under Authentication, set Allow public client flows to yes.
  3. Add these delegated API permissions: offline_access, openid, email, profile, User.Read, and Office 365 Exchange Online IMAP.AccessAsUser.All and SMTP.Send. For a Microsoft Graph account, also add Microsoft Graph Mail.ReadWrite, Mail.Send, Mail.ReadWrite.Shared, Mail.Send.Shared and MailboxSettings.Read.
  4. Put the client ID in config.json (outlookClientId), and the tenant ID (outlookTenantId) if it is not common.
  5. In Swanmail, go to Settings → Accounts → Add Account and choose Continue with Microsoft, then complete the sign-in flow.

Yahoo ​

Yahoo's mail scopes (mail-r, mail-w) are not self-service: an app has to apply to Yahoo and be approved before it can read mail over OAuth. For your own account, use an app password:

  1. In Yahoo, go to Account Info → Account security → Generate app password.
  2. In Swanmail, go to Settings → Accounts → Add Account, enter your Yahoo address and the app password. The server fields fill in by themselves.

Swanmail has no Yahoo OAuth sign-in.

Fastmail ​

Fastmail has no self-service OAuth app registration, and Swanmail has no Fastmail OAuth sign-in. Add the account by hand with either an API token, which syncs and sends over JMAP, or an app password, which uses IMAP and SMTP: Fastmail's JMAP endpoint accepts bearer tokens alone, never a password.

  1. In Fastmail, go to Settings → Privacy & Security → Manage API tokens and create a new token. Give it Email access and, to send, Email submission; do not make it read-only. Copy it: Fastmail shows it once. It starts with fmu1-.
  2. In Swanmail, go to Settings → Accounts → Add Account, choose or add manually, enter your Fastmail address, and paste the token into the Password field. The server fields fill in by themselves, for any of Fastmail's domains and for your own domain hosted there.
  3. Swanmail recognises the token, signs in to JMAP with it as a bearer token, and the account syncs and sends over JMAP with a JMAP badge. A token Fastmail refuses is reported as such when you add the account.

A token opens JMAP only. If it lacks Email submission, sending falls back to SMTP, which a token cannot sign in to, and fails.

With an app password (IMAP and SMTP) ​

  1. In Fastmail, go to Settings → Privacy & Security → Manage app passwords and access and create a new app password with mail access (IMAP, SMTP).
  2. In Swanmail, go to Settings → Accounts → Add Account, choose or add manually, and enter your Fastmail address and the app password. The server fields fill in by themselves (imap.fastmail.com, smtp.fastmail.com).
  3. The account syncs over IMAP and sends over SMTP. Swanmail tries JMAP with the password first, which Fastmail refuses, so the account stays on IMAP; nothing else changes.

For JMAP, use an API token (above) instead.

QQ Mail, Tencent Exmail and NetEase ​

QQ Mail (qq.com, foxmail.com) and NetEase (163.com, 126.com, yeah.net) sign in with an authorization code, not the password you use on the web, and they have no OAuth sign-in for other apps:

  1. In the web mail's settings, turn on the IMAP/SMTP service and generate an authorization code. QQ Mail has it under Settings → Account, NetEase under Settings → POP3/SMTP/IMAP.
  2. In Swanmail, go to Settings → Accounts → Add Account, enter your address, and paste the code into the Password field. The servers fill in by themselves.

Tencent Exmail (imap.exmail.qq.com) and NetEase's enterprise mail (imap.qiye.163.com) are found from your company domain. Exmail takes your mail password, or a client-only password when secure login is on.

Some notes:

  • NetEase opens no mailbox for a client that does not name itself, so Swanmail sends the IMAP ID command after signing in to any server that offers it.
  • NetEase names its folders in Chinese (已发送, 草稿箱, 已删除, 垃圾邮件); Swanmail knows them as Sent, Drafts, Trash and Junk.
  • QQ Mail can file a copy of what you send over SMTP itself. Swanmail looks for that copy before it files its own, so a sent message is not kept twice. The same holds for Outlook and Gmail.
  • Folders you made in QQ Mail show over IMAP only when QQ Mail's IMAP settings let it collect them.

Generic IMAP/SMTP ​

In the Add Account dialog, use or add manually below the quick-setup buttons for any email host that exposes standard IMAP and SMTP endpoints.

When you leave the email field, Swanmail fills in the servers for addresses at Google, Microsoft, Yahoo, iCloud and Fastmail, including your own domain hosted at one of them: it reads the domain's MX records to see who receives its mail. It never overwrites a server you typed yourself. You will need:

  • IMAP host and port
  • SMTP host and port
  • Your email address and password (or app-specific password)

POP3 ​

In the Add Account dialog's manual form, switch Protocol from IMAP to POP3. You will need the POP3 host and port (995 with TLS; other ports are upgraded with STLS), plus an SMTP host and port for sending — POP3 only receives.

POP3 is a download protocol, not a sync protocol. It has one maildrop, no folders, no flags, and no way to tell the server what you have done with a message. So a POP3 account in Swanmail works like this:

  • One Inbox. Everything the server holds arrives there, up to the newest 200 messages on the first sync.
  • The local copy is the copy. Messages stay in Swanmail's database after they have been downloaded, including after they are gone from the server.
  • Read state, stars, folders and moves are local. They are real and they persist, but they live only in Swanmail — no other client and no webmail will see them, and there is nothing to sync them back to.
  • Deleting a message deletes your copy, not the server's.
  • No server-side search. Searching a POP3 account searches what has been downloaded, which is everything it has.
  • New mail is polled, every 30 seconds, because POP3 has no IDLE and no push channel.

Delete from the server after download ​

The add-account form offers Delete from the server after download for POP3 accounts. It is off by default, which leaves every message in the maildrop.

Turn it on and each message is deleted from the server as soon as Swanmail has stored it — the deletion is committed when the session ends, so an interrupted sync deletes nothing. This is what you want when the mailbox is small or shared with nothing else, and what you do not want if you also read the same account on a phone: whichever client downloads a message first will be the only one to have it. The setting is kept with the account in Swanmail's database.

Microsoft 365 over Graph ​

Many organizations turn IMAP off on their Microsoft 365 tenant. Continue with Microsoft signs in for IMAP and, before adding the account, tries an IMAP login with it. When the mailbox refuses, Swanmail adds nothing, shows the server's reason, and offers Connect with Microsoft Graph: Swanmail then talks to your mailbox over Microsoft's own API, which the tenant cannot switch off separately. Microsoft also stops third-party apps from reaching Exchange Online over EWS on 1 October 2026, so Graph is the long-term route for a work or school mailbox.

Graph needs a different permission, so choosing it opens the Microsoft sign-in page once more, asking you to approve that.

What it asks for ​

Connecting with Graph asks your Microsoft account to approve:

  • Read and write access to your mail — Swanmail has to mark messages read, star them, move them and create folders.
  • Send mail as you.
  • Read and write mail in mailboxes shared with you, and send from them — used only for the shared mailboxes you add.
  • Read your mailbox settings — only for the colours of your Outlook categories.
  • Read your basic profile — to confirm which address you just signed in as.
  • Keep you signed in, so you are not asked again each time.

Choosing IMAP asks for exactly what it always did, and nothing more. Your organization may still require an administrator to approve either one.

Swanmail checks it can actually read your folders before the account is created. A sign-in that succeeds while the mailbox stays out of reach — no Exchange licence, or a policy blocking the app — fails on the button rather than leaving you with an account that never works.

How it differs from IMAP ​

Nearly everything behaves the same: folders, read state, stars, moves, deleting, emptying Trash, creating and renaming folders, search, and sending all work and all reach the server.

Four differences are worth knowing:

  • New mail is checked on a timer rather than pushed: every 5 seconds while you are using the computer, every 30 seconds once it has had no keyboard or mouse input for five minutes. The push mechanism Graph offers needs a public web address to deliver to, which an app on your own computer does not have.
  • Sent mail is filed by Exchange, not by Swanmail, so a message you send appears in Sent Items on the next sync rather than instantly.
  • Message sizes are not shown. Graph does not report them.
  • A message can be about 3 MB at most, attachments included. That is the ceiling of the Graph call that sends a finished message, and a Graph account has no SMTP route to fall back on. Swanmail tells you before anything is sent.

Existing Microsoft accounts are left on IMAP. Nothing moves an account between protocols on its own — to switch, remove the account and add it again with Graph selected. Your local mail is re-downloaded.

Exchange Server (EWS) ​

For a mailbox on an on-premises Exchange server (Exchange 2013 or later) where IMAP is switched off, choose Exchange (EWS) as the protocol in the manual account form. Mail, folders, read state, stars, moves, search and sending all go through Exchange Web Services, the interface Outlook itself uses.

A Microsoft 365 or Outlook.com mailbox should not use this: Microsoft blocks third-party EWS access to Exchange Online from 1 October 2026. Use the Microsoft button with Microsoft Graph instead.

The form asks for less than an IMAP account:

  • Email and password. Signing in uses NTLM when the server offers it and Basic authentication otherwise. A server that only offers Kerberos ("Negotiate") cannot be used yet; ask the administrator to enable NTLM or Basic on EWS.
  • Server URL — optional. Left empty, Swanmail finds it with Autodiscover from your address. If that fails, type it: it usually looks like https://mail.example.com/EWS/Exchange.asmx.
  • Login name — optional. Many servers want DOMAIN\user or a user principal name rather than the email address.
  • Accept a certificate no public authority signed — for servers using an internal certificate authority. Only tick it for a server you trust on a network you trust.

There are no IMAP or SMTP fields: sending goes through the same Exchange endpoint, and Exchange files the Sent copy itself.

Differences from IMAP worth knowing:

  • New mail is checked on a timer rather than pushed: every 10 seconds while you are using the computer, every 30 seconds once it has been idle for five minutes.
  • Server search looks in your main folders (Inbox, Sent, Archive, Drafts and a few more), not every folder of a very large mailbox. Local search covers everything already downloaded.
  • This protocol has been built against Microsoft's specification and test vectors, not yet against a wide range of real servers. If sign-in or sync fails, the error text names the Exchange response code; please include it in a bug report.

Exchange extras ​

These apply to a Microsoft 365 account on Graph and to an Exchange Server (EWS) account alike, unless a paragraph says otherwise.

Shared mailboxes ​

If your organization has given you access to another mailbox — a team inbox such as support@, or a colleague's mailbox you manage — add it in Settings → Accounts → Edit → Shared mailboxes with its address and the name you want to see. After the next sync its folders appear in the sidebar under that name, as a group of their own beneath your folders. Reading, marking read, starring, moving between its folders, deleting (to its own Deleted Items) and server search all work there as they do in your own mailbox. A message cannot be moved from a shared mailbox into one of your own folders, or back: Exchange treats those as two separate mailboxes.

Swanmail uses the access your administrator granted (Full Access, or permissions on individual folders); it never asks the server to impersonate anyone. A mailbox you have no access to is skipped and the rest of the account keeps syncing. Removing a shared mailbox from the list removes its folders and the mail downloaded from it.

On Microsoft 365 this needs a permission to open other mailboxes, which Swanmail asks for when a Graph account is added. An account added with an earlier version never granted it: if a shared mailbox's folders do not appear, remove the account and add it again, or ask the administrator to approve Mail.ReadWrite.Shared and Mail.Send.Shared for the app across the organization.

Sending from a shared mailbox ​

Every shared mailbox you add is offered in the composer's From selector. Choosing it sends the message as that mailbox, which needs the Send As permission on it; the copy goes to your own Sent Items.

For more control, add the address as an alias as well (below) and tick Another mailbox. Two more options then appear:

  • Send on behalf — for the Send on Behalf permission. Recipients see "you on behalf of the mailbox".
  • Keep the sent copy in that mailbox — the copy goes to the shared mailbox's own Sent Items, where the rest of the team sees it, instead of yours.

If Exchange refuses — you hold neither permission, or the other one — the error says which mailbox and which permission, and nothing is sent.

Public folders ​

Exchange Server (EWS) only. The server's public folders appear under Public Folders in the sidebar after a full sync, up to 500 of them. Each shows its newest 50 messages or posts, and scrolling down loads older ones. Public folders are read-only in Swanmail: you can read, mark read or unread, and flag, but not move, delete or reorganise, and the app says so rather than trying.

Microsoft Graph has no way to reach public folders, so a Microsoft 365 account on Graph does not show them; the account settings say so too.

Categories and tags ​

Outlook categories and Swanmail tags are the same thing on these accounts. A message's categories appear as tags after the next sync — a category without a matching tag creates one, coloured like the category in Outlook on Microsoft 365 (on Exchange Server, which does not share its colours, it takes the default colour) — and a category removed in Outlook removes the tag. Tagging or untagging such a message in Swanmail sets its categories on the server, so Outlook shows the change too.

Names match regardless of capitals. A few things stay one-sided:

  • Renaming, recolouring or deleting a tag in Swanmail does not rename or delete the category in Outlook's master list.
  • A tag set with the command-line tool stays local until the message's tags are next changed in the app.
  • Tags on IMAP, JMAP and POP3 accounts never leave your computer, as before.

Send-as aliases ​

An account can send as more than its own address. In Settings → Accounts, open the account's alias list and add a name and address for each identity your provider already lets you use — a Gmail "Send mail as" address, a catch-all on your own domain, a Fastmail alias. The composer's From selector then lists them, and a reply to mail addressed to an alias picks that alias automatically. Swanmail refuses to send from an address that is not the account's own or one of its aliases; it does not verify the alias with your provider, which may rewrite or reject a From it does not recognise.

JMAP ​

Accounts on a provider that offers JMAP (currently detected for Fastmail) sync over JMAP instead of IMAP and show a JMAP badge in Settings → Accounts. Such accounts also send through JMAP: the message is submitted with EmailSubmission and filed in Sent by the server, with SMTP as the fallback when the server does not offer submission. On Fastmail an account gets JMAP when it signs in with a bearer token: OAuth, or an API token entered as the password. Its JMAP endpoint accepts nothing else, so an account added with an app password stays on IMAP.

Multiple accounts ​

Each account appears as a separate section in the sidebar. Click an account's address to open its Inbox, and its chevron to fold it away. Hold an account's header until the grip appears and drag it above or below another; Settings → Accounts lists them in the same order. Accounts and folders can be collapsed, and the sidebar opens the way you left it. Top-level folders can be reordered independently per account.

In Settings → Accounts, click an account to edit it. Its … menu holds the signature, the folder labels, the AI agent and Remove account…. Removing asks first: the account's mail on this device is deleted, imported mail included, and the mail on the server stays.