Skip to content
Skills Library
DevOps & cloud · Tool integration

linux-mail-server

/linux-mail-server

Use when operating or diagnosing Postfix, Exim, Dovecot, SMTP submission, mail queues, TLS, or SPF/DKIM/DMARC on a Linux mail host. Use linux-network-admin for general reachability and linux-dns-server when the task is authoritative zone operation.

Licence
MIT
Last repository change
24.10.2026

Assessment and security

100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
4
Scripts
0
HTML comments
2
URLs in SKILL.md
2
Deprecation

No signals detected. Repository changed on 24.10.2026, without references to retired models or APIs.

Licence

MIT, open: use and modify while retaining author attribution.

What to check before installing
  • SKILL.md zawiera komentarze HTML (2). Nie widać ich w podglądzie Markdown, a model je czyta.

What it does and when to use it

Use when operating or diagnosing Postfix, Exim, Dovecot, SMTP submission, mail queues, TLS, or SPF/DKIM/DMARC on a Linux mail host. Use linux-network-admin for general reachability and linux-dns-server when the task is authoritative zone operation.

Original author description

Use when operating or diagnosing Postfix, Exim, Dovecot, SMTP submission, mail queues, TLS, or SPF/DKIM/DMARC on a Linux mail host. Use linux-network-admin for general reachability and linux-dns-server when the task is authoritative zone operation.

How it works

  1. Distro support
  2. Use when
  3. Do not use when
  4. Required inputs
  5. Workflow
  6. Quality standards
  7. Anti-patterns
  8. Outputs
  9. References
  10. Evidence Produced
Original SKILL.md headings · 403 lines, 2,103 words
SKILL.md preview
---
name: linux-mail-server
description: Use when operating or diagnosing Postfix, Exim, Dovecot, SMTP submission, mail queues, TLS, or SPF/DKIM/DMARC on a Linux mail host. Use linux-network-admin for general reachability and linux-dns-server when the task is authoritative zone operation.
license: MIT
metadata:
  portable: true
  compatible_with:
  - claude-code
  - codex
  author: Peter Bamuhigire
  author_url: techguypeter.com
  author_contact: "+256784464178"
---

# Linux Mail Server

## Distro support

Postfix and Dovecot run on both families and their config layout
(`/etc/postfix/main.cf`, `/etc/dovecot/`) is **largely identical**;
`postconf`, `postmap`, `postqueue`, `newaliases` behave the same. The
differences are a few package names, the mail log path, and SELinux. Body uses
Debian/Ubuntu; the **RHEL family** (Fedora, RHEL, CentOS Stream, Rocky, Alma,
Oracle) equivalents are in the matrix.

| Concept | Debian/Ubuntu | RHEL family |
|---|---|---|
| Postfix package / unit | `postfix` | `postfix` (same) |
| Default MTA | sometimes `exim4` | `postfix` |
| Dovecot | `dovecot-core`, `dovecot-imapd` | `dovecot` |
| DKIM | `opendkim` (main) | `opendkim` (**EPEL**) |
| Mail log | `/var/log/mail.log` | `/var/log/maillog` |
| Config paths | `/etc/postfix`, `/etc/dovecot` | same |
| Tools | `postconf`, `postmap`, `postqueue`, `newaliases` | identical |

**RHEL-family gotchas:** `opendkim` (and some milters) come from **EPEL**
(`ensure_epel`) on RHEL/Rocky/Alma, but ship in main on Fedora. SELinux governs
Postfix/Dovecot — non-default mail-spool or maildir paths need the right
contexts (`restorecon`, `semanage fcontext`) and some integrations need
booleans. Mail logs are in `/var/log/maillog` (cross-ref `linux-log-management`).
Deep SELinux coverage is in `linux-server-hardening` / Phase 2.

In `sk-*` scripts use the `common.sh` primitives (`pkg_install`, `ensure_epel`,
`svc_name`) instead of hardcoding the family. See
[`linux-bash-scripting`](../../10-automation-and-scripting/linux-bash-scripting/SKILL.md) and
[`docs/multi-distro/plan.md`](../../docs/multi-distro/plan.md).

<!-- dual-compat-start -->
## Use when

- Managing Postfix, Exim, Dovecot, queue behavior, or SMTP testing.
- Debugging delivery failures, spam-folder placement, or TLS/authentication issues.
- Updating SPF, DKIM, or DMARC-related server-side behavior.

## Do not use when

- The task is general DNS hosting unrelated to mail service; use `linux-dns-server`.
- The task is generic network reachability without a mail-specific angle; use `linux-network-admin`.

## Required inputs

| Artefact | Source | Required? | If absent |
|---|---|---|---|
| Mail role, software, domain/hostname, and current configuration | Mail host and service owner | required | Return discovery commands; do not edit a guessed topology. |
| Symptom, timestamps, queue IDs, sender/recipient domain, and relevant redacted logs | Incident report and host | required for diagnosis | Mark the affected transport stage `not assessed`. |
| DNS/TLS/relay ownership and approved test recipient | Domain and service owners | required for change/test | Stop before publishing records or sending mail. |

## Workflow

1. Identify whether the issue is configuration, queueing, transport, or authentication.
2. Inspect current config, queue state, and relevant logs.
3. Apply the matching workflow below for reputation, submission, queue, or domain changes.
4. Re-test SMTP flow and authentication to confirm the result.
5. Stop if relay scope, DNS/TLS ownership, queue impact, test-recipient authority, or rollback is unresolved.
6. Recover by restoring the prior validated config/records, reloading the service, and retesting a controlled message before resuming the queue.

## Quality standards

- Verify with real SMTP tests and queue inspection, not assumption.
- Keep authentication records and mail config aligned.
- Separate transport problems from reputation and policy problems.

## Anti-patterns

- Treating spam placement as only connectivity. Fix: inspect SPF, DKIM, DMARC, reverse DNS, TLS, reputation, and message evidence separately.
- Flushing/deleting a queue before diagnosis. Fix: sample queue IDs, reasons, age, destination patterns, and logs first.
- Enabling an open relay or broad trusted network. Fix: restrict relay to authenticated/explicit clients and test rejection externally.
- Publishing mail-authentication records without alignment tests. Fix: validate selectors, policy, envelope/header domains, and authoritative DNS.
- Logging or sharing message bodies/credentials unnecessarily. Fix: use queue IDs, headers, and redacted protocol traces.

## Outputs

| Artefact | Consumer | Acceptance condition |
|---|---|---|
| Mail-path diagnosis or configuration change | Mail operator | Locates failure at submission, queue, DNS, transport, policy, mailbox, or reputation layer with evidence. |
| Authentication/TLS evidence | Domain owner | SPF/DKIM/DMARC alignment and certificate/hostname checks are observed, or explicitly unassessed. |
| Delivery verification | Service owner | Approved test mail receives expected SMTP codes and reaches the intended mailbox without creating an open relay. |

## References

- [`references/postfix-reference.md`](references/postfix-reference.md)
- [`references/email-authentication.md`](references/email-authentication.md)
- [`references/debugging-delivery.md`](references/debugging-delivery.md)

## Evidence Produced

| Artefact | Acceptance condition |
|---|---|
| Mail-operation evidence | Includes redacted config, queue samples, log timeline, SMTP transcript, DNS/authentication/TLS results, authorised headers, and rollback. |

## Capability contract

Diagnosis defaults to read-only. Mail configuration, queue mutation, DNS publication, certificate changes, service reloads, or sending external test mail require explicit authority. Never expose mailbox credentials, private keys, or message content beyond approved evidence.

## Degraded mode

Without host, DNS, or recipient access, assess only available layers and label the rest `not assessed`. A successful TCP connection is not a delivery or reputation pass.

## Decision rules

| Choice | Action | Failure or risk avoided |
|---|---|---|
| Queue deferral cluster | Inspect enhanced status/log cause before retry | Amplifying a persistent failure. |
| Authentication passes but spam persists | Examine reputation/content/provider feedback | Rewriting healthy transport config. |
| Submission auth failure | Test SASL/TLS listener and policy | Weakening relay controls. |

## Worked example

For a growing Postfix queue to one provider, sample deferred queue IDs, correlate enhanced status codes and logs, verify DNS/TLS/authentication, correct the evidenced cause, reload only after config validation, retry a small sample, and record delivery before releasing the remainder.

<!-- dual-compat-end -->

**This skill is self-contained.** Every command below is a standard mail
tool (`postfix`, `postqueue`, `postconf`, `swaks`, `openssl`, `dig`) present on
both Debian/Ubuntu and the RHEL family; body examples use Debian/Ubuntu
syntax, with RHEL-family differences in the **Distro support** matrix above.
The `sk-*` scripts in the **Optional fast path** section
are convenience wrappers — never required.

This skill covers running and debugging mail on a Debian/Ubuntu or RHEL-family server:
Postfix (default), Exim (alternative), Dovecot for IMAP, and the three
pillars of email authentication — SPF, DKIM, DMARC.

It does **not** own:

- **Firewall rules for SMTP ports** — `linux-firewall-ssl`.
- **DNS records themselves** (MX, SPF, DKIM, DMARC live at the DNS host) —
  but this skill *validates* them.
- **Mail clients** — out of scope.

Informed by *Linux Network Administrator's Guide* (Sendmail/Exim chapters,
translated to Postfix) and modern email authentication practice.

---

## When to use

- Setting up a server to send mail (transactional, notifications, relay).
- Diagnosing "my email goes to spam."
- Checking a mail queue for stuck messages.
- Testing SMTP from the command line (EHLO, STARTTLS, auth, RCPT).
- Validating SPF, DKIM, DMARC records for a domain.
- Inspecting a remote MX's reachability and TLS.

## When NOT to use

- Setting up cloud email (SES, SendGrid, Postmark) — those are API-based.
- Managing DNS records at a registrar — use the registrar's UI or API.

---

## Standing rules

1. **Never run a mail server without SPF + DKIM + DMARC.** Unauthenticated
   mail is treated as spam by every modern receiver.
2. **Never relay mail for third parties without authentication.** Open
   relays are abuse vectors. `mynetworks` in `main.cf` must be
   `127.0.0.0/8` only by default.
3. **Always enable TLS for submission (port 587).** STARTTLS only, reject
   plain auth.
4. **Always validate config before reload.** `postfix check` for Postfix,
   `exim -bV` for Exim.
5. **The queue is the first thing to check on delivery problems.**
6. **Log everything to `/var/log/mail.log`** (syslog) *and*
   `journalctl -u postfix` — both exist on modern Ubuntu.
7. **Reverse DNS (PTR) of the sending IP must match the HELO name.**
   Mismatched PTR is the single biggest reason mail is flagged as spam.

---

## Quick reference — manual commands

### Postfix config and status

```bash
# Validate config — always run before reload
sudo postfix check

# Show effective config (difference from default)
postconf -n

# Reload
sudo postfix reload

# Or full restart if service behavior is stuck:
sudo systemctl restart postfix

# Service status
sudo systemctl status postfix --no-pager
sudo journalctl -u postfix -n 50 --no-pager
sudo tail -f /var/log/mail.log
```

### Queue inspection

```bash
# Show queue
sudo postqueue -p
sudo mailq                                       # alias

# Count by status
sudo postqueue -p | grep -c '^[A-F0-9]'

# Inspect a specific message
sudo postcat -q <queue-id>

# Force a flush (try delivery now)
sudo postqueue -f

# Delete a specific stuck message
sudo postsuper -d <queue-id>

# Delete everything (use with extreme care)
sudo postsuper -d ALL
```

### SMTP testing from the command line

```bash
# Install swaks if needed
sudo apt install swaks

# Full SMTP conversation with TLS and auth
swaks --server mail.example.com \
      --port 587 \
      --from sender@example.com \
      --to recipient@example.org \
      --auth LOGIN \
      --auth-user sender@example.com \
      --tls \
      --header "Subject: test $(date)" \
      --body "test body"

# Just the handshake (no auth, no send)
swaks --server mail.example.com --port 587 --quit-after STARTTLS

# With openssl (lower level):
openssl s_client -starttls smtp -connect mail.example.com:587 -crlf
# Type: EHLO test.example.com
# Then: QUIT
```

### Email authentication checks

```bash
# SPF lookup
dig +short TXT example.com | grep spf1

# DKIM selector (replace "default" with your actual selector)
dig +short TXT default._domainkey.example.com

# DMARC
dig +short TXT _dmarc.example.com

# MX record with priorities
dig +short MX example.com

# Reverse DNS (PTR) — must match HELO
dig +short -x $(curl -s https://api.ipify.org)

# Online checkers (for humans, but record the dig output yourself first):
# - https://mxtoolbox.com
# - Gmail Postmaster Tools
```

Full email-auth deep dive (record syntax, DKIM key generation via
`opendkim-genkey`, DMARC reporting, example DNS zone snippet) — see
[`references/email-authentication.md`](references/email-authentication.md).

---

## Typical workflows

### Workflow: "Our emails are going to spam"

Walk [`references/debugging-delivery.md`](references/debugging-delivery.md).
Condensed:

```bash
# 1. Queue health
sudo postqueue -p

# 2. Reject reason on a deferred message
sudo postcat -q <queue-id> | tail -20

# 3. SPF / DKIM / DMARC present?
dig +short TXT example.com | grep spf1
dig +short TXT default._domainkey.example.com
dig +short TXT _dmarc.example.com

# 4. PTR matches HELO?
dig +short -x $(postconf -h inet_interfaces | awk '{print $1}')
postconf -h myhostname

# 5. TLS working for submission?
swaks --server mail.example.com --port 587 --quit-after STARTTLS
```

### Workflow: "Is port 587 submission working?"

```bash
swaks --server mail.example.com \
      --port 587 \
      --auth LOGIN \
      --auth-user bot@example.com \
      --tls
```

Reports each step (connection, STARTTLS, AUTH, MAIL FROM, RCPT TO, DATA).

### Workflow: "The queue is growing"

```bash
# 1. How bad?
sudo postqueue -p | tail -5   # last line says "Total requests"

# 2. What's stuck and why?
sudo postqueue -p | head -30

# 3. Pick a message and see the specific rejection:
sudo postcat -q <queue-id>

# 4. Common fixes:
#    - Greylist: just wait; Postfix will retry automatically
#    - TLS handshake error: check recipient server's cert, your own
#    - Auth required: fix relay credentials
#    - Relay denied: check mynetworks, smtpd_recipient_restrictions
```

### Workflow: "Add a new domain to an existing Postfix"

```bash
# 1. Edit main.cf — add to mydestination or virtual_mailbox_domains
sudo nano /etc/postfix/main.cf

# 2. If using virtual mailboxes, update the virtual maps:
sudo nano /etc/postfix/virtual_alias_maps
sudo postmap /etc/postfix/virtual_alias_maps

# 3. Validate
sudo postfix check

# 4. Reload
sudo postfix reload

# 5. Test with swaks
```

---

## Troubleshooting / gotchas

- **PTR record mismatch is the #1 spam trigger.** If your server's IP
  reverse-resolves to `vps-12345.provider.net` but Postfix HELOs as
  `mail.example.com`, receivers downgrade you immediately. Fix the PTR
  at the VPS provider.
- **`postfix reload` doesn't reload everything.** Changes to `master.cf`
  require `sudo systemctl restart postfix`. `postfix reload` only
  re-reads `main.cf`.
- **TLS fails on port 465 but works on 587.** Port 465 is implicit TLS
  (SMTPS), 587 is STARTTLS. They need separate service stanzas in
  `master.cf` — enable both.
- **DKIM signs but receivers fail DMARC.** Check alignment: the signing
  domain (`d=`) must match the `From:` header domain (relaxed alignment)
  or exactly (strict). A DKIM-signed bounce that uses the mail server's
  hostname as `d=` won't align with the sender's domain.
- **Postfix is silently deferring.** Look in `/var/log/mail.log` — the
  rejection reason is there. The queue only shows the summary.
- **Dovecot and Postfix disagree about a user.** Postfix's
  `virtual_mailbox_maps` must match Dovecot's `passdb` / `userdb`. Use
  a single source of truth (MySQL, LDAP, or a flat file) and point both
  at it.

---

## References

- [`references/postfix-reference.md`](references/postfix-reference.md) —
  full Postfix reference: `main.cf` parameters, `master.cf`, queue
  management, 3 complete config examples.
- [`references/email-authentication.md`](references/email-authentication.md) —
  SPF, DKIM (with opendkim), DMARC deep dive with DNS record examples.
- [`references/debugging-delivery.md`](references/debugging-delivery.md) —
  decision tree for delivery problems.
- Book: *Linux Network Administrator's Guide* (Kirch & Dawson) — mail
  chapters (Sendmail/Exim, translated to Postfix).
- Book: *Ubuntu Server Guide* (Canonical) — Postfix and Dovecot.
- Man pages: `postfix(1)`, `postconf(5)`, `master(5)`, `postqueue(1)`,
  `postcat(1)`, `swaks(1)`.

---

## Script availability

No wrapper commands for this skill are shipped in this checkout. Use the native procedures above; planned wrappers remain in [the script inventory](../../docs/engine-design/script-inventory.md) until their source files are present.
Files in this package (4)
  • SKILL.md 15 KB
  • references/debugging-delivery.md 14 KB
  • references/email-authentication.md 18 KB
  • references/postfix-reference.md 21 KB

Versions

The database has no other skills named linux-mail-server.

Database snapshot: 13.11.2026 · package version a8ef64353507 (SHA-256 digest of the entire package)

Downloads in the last 30 days: 0 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 100postfix
    Expert skill for Postfix MTA versions 3.9 and 3.10. Covers main.cf/master.cf configuration, TLS (STARTTLS, DANE, MTA-STS), SASL authentication, virtual domains, milter integration (OpenDKIM, OpenDMARC, Rspamd), postscreen, queue management, access controls, rate limiting, and…
  • 100mail-auth
    Check a domain's email authentication (SPF, DKIM, DMARC, MX, MTA-STS, TLS-RPT) with a deterministic zero-dependency checker, print the exact DNS records to publish, and re-check until propagation completes. Use when mail "goes to spam", "never arrives", "fails authentication",…
  • 100billionmail
    Use when self-hosting bulk email or transactional mail — Postfix + Dovecot, newsletter campaigns with rate limiting, DKIM/MX/PTR setup, bounce and unsubscribe handling, delivery analytics, webmail. BillionMail 4.9: docker compose / install.sh deployed mail platform by the…
  • 100email-infrastructure
    Email deliverability and DNS-based email authentication covering SPF, DKIM, DMARC, MX, PTR, and BIMI records, SMTP relay service configuration (SendGrid, SES, Postmark, Mailgun), self-hosted Postfix relay basics, and deliverability testing. USE WHEN: - Setting up or auditing…
  • 90httpfy-network-checks
    Check DNS records, email authentication (SPF, DKIM, DMARC, BIMI, MTA-STS), TLS certificates, domain WHOIS and expiry, IP and ASN data, blocklists and network reachability (ping, traceroute, TCP port) using the free httpfy.io MCP server. Use when debugging domains, mail delivery,…
  • 100email-auth-check
    Check a domain's email authentication from live DNS (SPF, DKIM, DMARC, MX, MTA-STS, TLS-RPT, BIMI, DNSSEC and CAA) and write the exact DNS records that fix it. Use when someone asks why their email lands in spam or gets rejected, how to set up SPF, DKIM or DMARC, to audit a…

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.