View source for Services/SnappyMail

''As of: 2026-07-05 — migrated from `services/SNAPPYMAIL.md`''

= SnappyMail Webmail =

== Container & Files ==

{| class="wikitable"
|-
! Item
! Value
|-
| Container
| <code>snappymail</code>
|-
| Compose
| <code>/library/snappymail-app/docker-compose.yml</code>
|-
| Data dir
| <code>/library/snappymail-app/data/</code>
|-
| Image
| <code>djmaze/snappymail:latest</code>
|-
| Internal port
| <code>8888</code>
|-
| External port
| <code>8890</code> → proxied via VPS nginx
|}

<syntaxhighlight lang="bash">
cd /library/snappymail-app && docker compose up -d
docker logs --tail=50 snappymail 2>&1 | strings
</syntaxhighlight>

----

== Architecture Note — Unified vs Multi-Account ==

'''SnappyMail connected accounts ≠ unified inbox.'''

Adding external accounts (Gmail, iCloud, SDF) in SnappyMail Settings → Accounts shows them as separate silos side-by-side. There is no combined view.

'''The right approach for a unified inbox''' is to use '''getmail''' to pull all external accounts into Stalwart, then connect SnappyMail (and phones/clients) only to Stalwart. Sieve rules on Stalwart do the filtering. This way:
* One IMAP server to connect to from anywhere
* All mail filtered by sieve on arrival
* SnappyMail just sees one account with well-organized folders

Use SnappyMail's "additional accounts" feature only for occasional read-only access to an external account, not as the primary mail flow mechanism.

----

== Critical: MTU Must Be 1280 ==

The host's surfshark WireGuard VPN (surfshark_wg) has MTU 1280. All Docker bridge networks must match or large TLS packets (Server Hello + cert chain, ~4–6 KB) get silently dropped mid-handshake. '''Without MTU 1280, all external IMAP SSL connections hang for ~2 minutes then reset.'''

The <code>docker-compose.yml</code> already has this fix:

<syntaxhighlight lang="yaml">
networks:
  default:
    driver: bridge
    driver_opts:
      com.docker.network.driver.mtu: 1280
</syntaxhighlight>

If SnappyMail is redeployed or the network is recreated, verify MTU with:
<syntaxhighlight lang="bash">
docker network inspect snappymail-app_default | grep -i mtu
</syntaxhighlight>

After changing docker-compose.yml, you must <code>docker compose down && docker compose up -d</code> — <code>restart</code> alone does NOT recreate the network.

----

== Domain Config Files ==

Path: <code>/library/snappymail-app/data/_data_/_default_/domains/</code>

One JSON file per domain. Controls IMAP/SMTP server settings for that domain's accounts.

'''Ownership:''' Files must be owned by <code>uid 82 / gid 82</code> (container's www-data). If created as root, SnappyMail can't read them and shows "Domain is not allowed" or "no domain configuration".

<syntaxhighlight lang="bash">
sudo chown 82:82 /library/snappymail-app/data/_data_/_default_/domains/*.json
</syntaxhighlight>

Active domain configs:
{| class="wikitable"
|-
! File
! Server
! Notes
|-
| <code>wilsoz.com.json</code>
| <code>host.docker.internal</code>
| Stalwart — primary account
|-
| <code>craniumslows.com.json</code>
| <code>host.docker.internal</code>
| Stalwart — secondary address
|-
| <code>gmail.com.json</code>
| <code>imap.gmail.com:993</code>
| Requires App Password
|-
| <code>icloud.com.json</code>
| <code>imap.mail.me.com:993</code>
| Requires App Password
|-
| <code>me.com.json</code>
| <code>imap.mail.me.com:993</code>
| Same server as iCloud
|-
| <code>sdf.org.json</code>
| <code>mx.sdf.org:993</code>
| <code>shortLogin: true, lowerLogin: true</code>
|}

'''Editing domain configs:''' Do NOT bind-mount individual files — the container entrypoint does <code>sed -i</code> substitutions on its config files, which fails with "Resource busy" on bind-mounted files. Bind-mount the whole <code>data/</code> directory (already the case).

----

== Disabled Domains List ==

Path: <code>/library/snappymail-app/data/_data_/_default_/domains/disabled</code>

Plain text, one domain per line. Domains listed here cannot be added as accounts.

Current contents (as of 2026-02-22):
<syntaxhighlight lang="text">
outlook.com
qq.com
yahoo.com
hotmail.com
</syntaxhighlight>

<code>gmail.com</code> was in here by default — removed so users can add Gmail accounts.

----

== Stalwart Connection (wilsoz.com / craniumslows.com) ==

SnappyMail connects to Stalwart via <code>host.docker.internal</code> (resolves to the Docker bridge gateway → host → Stalwart port 993/587).

<syntaxhighlight lang="json">
{
  "IMAP": { "host": "host.docker.internal", "port": 993, "type": 1 },
  "SMTP": { "host": "host.docker.internal", "port": 587, "type": 2 }
}
</syntaxhighlight>

The <code>extra_hosts: ["host.docker.internal:host-gateway"]</code> in docker-compose.yml enables this.

----

== External Account App Passwords ==

For reference (these are app-specific passwords, not account passwords):

{| class="wikitable"
|-
! Account
! IMAP Server
! App Password
|-
| craniumslows@gmail.com
| imap.gmail.com:993
| <code>jeuwezdxaoaysvni</code>
|-
| thewilson@gmail.com
| imap.gmail.com:993
| <code>wikjuwnmklkeisid</code>
|-
| marcusthewilson@me.com
| imap.mail.me.com:993
| <code>pekx-kvid-iopx-lhyy</code>
|-
| mnw@sdf.org
| mx.sdf.org:993
| (SDF account password)
|}

----

== Troubleshooting ==

'''"Can't connect to host ssl://..."'''
* First check: MTU. Run <code>docker network inspect snappymail-app_default | grep -i mtu</code> — must be 1280.
* Test SSL from inside container: <code>docker exec snappymail php -r "...stream_socket_client('ssl://imap.gmail.com:993'...)"</code>
* If MTU is fine, test from host: <code>curl -v --max-time 10 imaps://imap.gmail.com:993</code>

'''"Domain is not allowed" / "no domain configuration"'''
* Check <code>disabled</code> file — is the domain listed there?
* Check if a <code>.json</code> file exists for that domain
* Check ownership: <code>sudo ls -la /library/snappymail-app/data/_data_/_default_/domains/</code>
* Fix: <code>sudo chown 82:82 /library/snappymail-app/data/_data_/_default_/domains/<domain>.json</code>

'''Admin panel'''
* URL: <code>http://localhost:8890/?admin</code> (or via VPS proxy)
* Default admin password set on first run, stored in <code>data/_data_/_default_/configs/application.ini</code>