Dovecot IMAP Basics

Introduction¶

In a self-hosted mail stack, Postfix receives and sends mail (MTA); Dovecot stores it and serves it to users over IMAP/POP3 (MDA + access). It also usually handles authentication for both — Postfix asks Dovecot to verify SMTP AUTH.

Storage formats¶

Maildir is the safe default. mdbox for very large or high-volume mailboxes.

# 10-mail.conf
mail_location = maildir:~/Maildir
# or: mdbox:~/mdbox
namespace inbox {
  inbox = yes
  mailbox Trash { auto = subscribe; special_use = \Trash }
  mailbox Sent  { auto = subscribe; special_use = \Sent }
  mailbox Junk  { auto = subscribe; special_use = \Junk }
}

Authentication: passdb and userdb¶

• passdb — verifies the password (checks against /etc/dovecot/users, SQL, LDAP, PAM, etc.).
• userdb — supplies the user's UID/GID, home, and mail location after auth succeeds.

# 10-auth.conf
disable_plaintext_auth = yes         # only over TLS
auth_mechanisms = plain login

# a simple file-based setup (passwd-file)
passdb {
  driver = passwd-file
  args = scheme=ARGON2ID /etc/dovecot/users
}
userdb {
  driver = passwd-file
  args = /etc/dovecot/users
  default_fields = uid=vmail gid=vmail home=/var/vmail/%d/%n
}

/etc/dovecot/users line: [email protected]:{ARGON2ID}$argon2id$...::::::

For virtual domains, SQL (dovecot-sql.conf.ext) or LDAP passdb/userdb is common.

The Postfix hand-off (LMTP)¶

Postfix receives mail, then hands local delivery to Dovecot via LMTP (better than the older deliver binary — supports SIEVE, quota, multiple recipients):

# Dovecot 10-master.conf
service lmtp {
  unix_listener /var/spool/postfix/private/dovecot-lmtp {
    mode = 0600
    user = postfix
    group = postfix
  }
}

# Postfix main.cf
mailbox_transport = lmtp:unix:private/dovecot-lmtp
virtual_transport = lmtp:unix:private/dovecot-lmtp

Dovecot also runs the auth socket Postfix uses for SMTP AUTH:

service auth {
  unix_listener /var/spool/postfix/private/auth {
    mode = 0660
    user = postfix
    group = postfix
  }
}

SSL/TLS¶

# 10-ssl.conf
ssl = required
ssl_cert = </etc/letsencrypt/live/mail.example.com/fullchain.pem
ssl_key  = </etc/letsencrypt/live/mail.example.com/privkey.pem
ssl_min_protocol = TLSv1.2

IMAPS 993, POP3S 995, or STARTTLS on 143/110. After renewing certs, doveadm reload (or restart).

SIEVE (server-side filtering)¶

The pigeonhole plugin runs user filter scripts at delivery — sorting, vacation autoresponders, forwarding. Managed over ManageSieve (port 4190) or a webmail.

Verification and troubleshooting¶

doveconf -n                          # effective config (like nginx -T)
doveadm auth test [email protected]   # test a login without a client
doveadm user [email protected]        # show resolved userdb (home, uid, mail location)
doveadm mailbox list -u [email protected]
doveadm quota get -u [email protected]
tail -f /var/log/dovecot.log /var/log/mail.log

• IMAP login fails "Authentication failed" — doveadm auth test isolates passdb from the client. Wrong scheme prefix in the users file, plaintext auth attempted without TLS (disable_plaintext_auth = yes), or PAM/SQL/LDAP backend unreachable.
• Login OK but no mail / "Mailbox doesn't exist" — userdb mail_location or home wrong, or the vmail user can't read the Maildir (ownership/perms). doveadm user shows what Dovecot computed.
• Postfix can't deliver: "connect to private/dovecot-lmtp ... No such file" — the LMTP unix_listener path is outside Postfix's chroot (/var/spool/postfix/ prefix), or Dovecot isn't running, or socket perms.
• SMTP AUTH fails in Postfix — the private/auth socket user/group/mode, and smtpd_sasl_type = dovecot, smtpd_sasl_path = private/auth in Postfix.
• "Disk quota exceeded" but there's space — Dovecot quota plugin; doveadm quota recalc -u user. For mdbox, doveadm purge -u user reclaims deleted-message space.
• Certs expired / clients warn — doveadm reload after renewal; check ssl_cert/ssl_key paths point at fullchain.pem (not cert.pem).
• Slow IMAP with big folders (Maildir) — expected; move that user to mdbox, or ensure indexing (INDEX / mail_location with a separate fast index path).

Related tools and reading¶

• On-site: SMTP test, SSL Certificate Checker, DNS MX Lookup.
• Related posts: Postfix as a null client, Zimbra: common issues and how to fix them.