POP3 configuration

Yarilo implements POP3 (RFC 1939) with STLS (RFC 2595), UIDL, CAPA, and XCLIENT.

Listeners: services.pop3s (implicit TLS, port 995) and services.pop3 (STARTTLS, port 110). See Services configuration for listener-level settings (port, ssl_mode, haproxy_protocol, etc.).

---

protocol.pop3

Protocol-level behaviour, shared across both POP3 listeners.

pop3_no_flag_updates

Default

false

Type

boolean

Helm

protocol.pop3.pop3_no_flag_updates

false sets \Seen on retrieved messages at QUIT. true changes no flags on retrieval.

pop3_reuse_xuidl

Default

false

Type

boolean

Helm

protocol.pop3.pop3_reuse_xuidl

Use the X-UIDL message header as the UIDL value. Lets mail migrated from Courier, qmail or cPanel keep its UIDLs.

pop3_uidl_format

Default

%u.%v

Type

string

Helm

protocol.pop3.pop3_uidl_format

UIDL format string; the variables are listed below.

pop3_uidl_duplicates

Default

rename

Type

string

Values

allow rename

Helm

protocol.pop3.pop3_uidl_duplicates

allow sends duplicate UIDLs as they are. rename appends a -N suffix so every UIDL is unique.

pop3_enable_last

Default

false

Type

boolean

Helm

protocol.pop3.pop3_enable_last

Advertise and handle the LAST command (RFC 1460).

pop3_delete_type

Default

expunge

Type

string

Values

expunge flag

Helm

protocol.pop3.pop3_delete_type

See also

pop3_deleted_flag

expunge removes a deleted message from disk at QUIT. flag sets pop3_deleted_flag instead, so the message stays visible over IMAP.

pop3_deleted_flag

Default

none

Type

string

Helm

protocol.pop3.pop3_deleted_flag

IMAP flag set when pop3_delete_type is flag, for example $POP3Deleted.

pop3_save_uidl

Default

false

Type

boolean

Helm

protocol.pop3.pop3_save_uidl

Persist computed UIDLs to a pop3.uidl file next to the folder's index. Later sessions load them, so UIDLs stay the same across index rebuilds and backend changes.

pop3_lock_session

Default

false

Type

boolean

Helm

protocol.pop3.pop3_lock_session

Create a dotlock at $HOME/yarilo-pop3-session.lock after login, so another replica on the same PVC cannot serve the user at the same time. Locks older than 10 minutes are stolen.

pop3_uidl_format variables

Variable	Description
%u	Message UID.
%v	Mailbox UIDValidity.
%f	Filename (Maildir only).
%g	GUID (128-bit hex, dbox/mdbox).
%m	MD5 of the filename.

Common presets:

Format	Result example	Compatible with
%u.%v	1234.5678	yarilo default
%08Xu%08Xv	000004D2000016C2	the reference
%f	1700000000.M123P456.host:2,S	Courier (Maildir)

---

Soft-delete (flag mode)

When pop3_delete_type: flag, messages deleted by a POP3 client are not removed from disk. Instead the flag defined by pop3_deleted_flag is set, and the message remains visible in IMAP. This allows users to switch between POP3 and IMAP without losing mail.

protocol:
  pop3:
    pop3_delete_type: flag
    pop3_deleted_flag: "$POP3Deleted"

---

Migration from other servers

To migrate users from Courier, qmail, or cPanel without changing UIDL values (which would cause POP3 clients to re-download all mail):

protocol:
  pop3:
    pop3_reuse_xuidl: true
    pop3_uidl_format: "%f"      # match the source server's format
    pop3_uidl_duplicates: rename

---

UIDL stability (pop3_save_uidl)

By default, UIDLs are computed fresh each session from pop3_uidl_format. If the index is rebuilt or a backend migration changes filenames, UIDLs may change — causing POP3 clients to re-download mail they already have.

Enable pop3_save_uidl to persist the computed UIDL for each message:

protocol:
  pop3:
    pop3_save_uidl: true

UIDLs are saved to a pop3.uidl file next to the folder's yarilo.index, in the index directory (one uid\tuidl pair per line) at the end of each session via atomic write. On the next session, saved values are loaded and used for existing UIDs; new messages get fresh UIDLs that are then persisted.

Priority when multiple sources exist: pop3_reuse_xuidl header → saved index entry → format-computed value.

---

Session locking (pop3_lock_session)

In multi-replica deployments (yarilo-pop3 replicas > 1 on a shared PVC), two pods could serve the same user simultaneously — one via POP3 and one via IMAP. Enable pop3_lock_session to prevent this:

protocol:
  pop3:
    pop3_lock_session: true

After login, the session creates $HOME/yarilo-pop3-session.lock. A second session for the same user on any pod that shares the filesystem will be rejected with -ERR mailbox already in use. The lock is released when the session ends (QUIT or disconnect). Locks older than the session idle timeout, 10 minutes, are automatically treated as stale and stolen.