vps/runbooks/mailcow-smtp-client.md

# Runbook: use mailcow SMTP / IMAP (client)

## Purpose

Reference for configuring mail clients against the mailcow SMTP/IMAP endpoints.

## Scope

- Applicable: [mx2.windy.me](../hosts/mx2.windy.me.md) client submission (587/465) and IMAP/POP (993/995).
- Not applicable: server-side mailcow configuration or administration.

## Ownership

- Owner: personal ops (Windy)
- Last reviewed: 2026-08-17
- Related systems: mx2.windy.me (SMTP/IMAP client endpoints)

Target: [mx2.windy.me](../hosts/mx2.windy.me.md)  
Prerequisite: a mailbox on `windy.me` (password from mailcow UI, not the admin account unless it is that mailbox).

Clients should use **submission** to send. Do **not** use port 25 as a desktop/app outbound port.

## Send (SMTP)

| Item | Value |
|------|--------|
| Server | `mx2.windy.me` |
| Port | **587** (STARTTLS) — preferred |
| Alt port | **465** (SSL/TLS) |
| Username | Full address, e.g. `zhiqiang@windy.me` |
| Password | Mailbox password |
| Auth | Required (LOGIN / PLAIN) |

Match encryption to the port: 587 → STARTTLS; 465 → SSL/TLS (not STARTTLS).

From address should be that mailbox or an allowed alias on the same domain.

## Receive (IMAP / POP)

| Protocol | Server | Port |
|----------|--------|------|
| IMAPS | `mx2.windy.me` | **993** |
| POP3S | `mx2.windy.me` | **995** |

Username = full email address; same mailbox password.

## Webmail

- UI / SOGo: https://mx2.windy.me  
- Log in with the same mailbox credentials.

## CLI smoke test (optional)

```bash
swaks --to someone@example.com \
  --from YOU@windy.me \
  --server mx2.windy.me --port 587 -tls \
  --auth LOGIN --auth-user YOU@windy.me --auth-password 'MAILBOX_PASSWORD'
```

Do not commit or paste real passwords into this repo.

## Auth failures — quick checks

- Username is the **full** email, not a local part alone
- Password is the **mailbox** password (not unrelated host/root secrets)
- Port/TLS mode mismatch (587 vs 465)
- Account active in mailcow; not rate-limited / fail2banned after bad attempts
- Apps that store SMTP in their own config (e.g. Vaultwarden `config.json`) may keep a **stale** password even when `.env` is correct — verify AUTH against the effective config ([vaultwarden-health](vaultwarden-health.md) §5)

## Safety

- Do not commit or paste real passwords into this repo or chat.
- Use submission (587/465) for client sending; never use port 25 as a desktop/app outbound port.
- If live state conflicts with the endpoint values above, `STOP` and report; do not change server-side settings during this reference check.