58. pepsi-stage-secretary

Hold mail from unknown senders until they confirm by replying.

58.1. Role

pepsi-stage-secretary is confirm-to-send, after qmail’s qsecretary. Mail from a sender that no whitelist knows is held, and the sender is asked, in their own language, to reply once. The reply whitelists them and releases everything held for them; later mail from them passes pepsi-stage-check-whitelist and is never held again. Without a reply by HOLD_TIME the held mail takes the timeout path (BOUNCE_STAGE if one is wired, else it is deleted). Reference: pepsi-stage-secretary(1).

It is weaker than pay-to-send (pepsi-stage-anti-spam): a spammer with a working mailbox can reply, and the declaration that the sender agrees to (PENALTY) is a legal deterrent rather than an economic one. It is still worth having, because most bulk mail comes from addresses that cannot receive, and a real correspondent only has to reply once. Supported Features compares the two.

58.2. What is challenged

Locally submitted mail and a whitelisted sender (state.spam = false) pass untouched; state.spam = true takes the timeout path. A null-sender message cannot be challenged, so it passes only with a proof that it answers mail that this host sent: a Pepsi-Origin field that verifies and whose nonce is still tracked. Without that proof it is unchallengeable, so a forged bounce cannot carry a stranger’s mail past the gate (with [pepsi-origin] ENABLED = no nothing can be proven and every bounce passes). Everything else is challenged, except in the cases below, where the message goes to UNCHALLENGEABLE_STAGE (or takes the timeout path when that is unset):

  • RFC 3834 says do not answer it (lists, Precedence: bulk, Auto-Submitted:, service senders, delivery reports), or the sender failed SPF or DMARC outright (a fail verdict; softfail, neutral and none do not count); these are the shared rules for automatic replies, which pepsi-stage-vacation also applies;

  • the sender is also one of the recipients;

  • its From: is not exactly the envelope sender (the challenge goes to MAIL FROM and the whitelist matches From:, so they must be one address);

  • REQUIRE_AUTHENTICATED (default on) is set and neither SPF nor DMARC passed, which guards against backscatter;

  • the sender has had MAX_CHALLENGES_PER_SENDER (default 5) challenges in the last 24 hours, across every whitelist;

  • WHITELIST_NAME does not expand for the recipients, or there is no served domain to put the reply address at.

One challenge covers every message from one sender to one whitelist: a second message joins the open challenge and inherits its deadline. A message whose recipients expand WHITELIST_NAME to different lists is split one row per list.

58.3. The challenge and the reply

The challenge is a null-sender text/plain message with Auto-Submitted: auto-replied, injected at RESPONSE_STAGE. Its From: and Reply-To: are the reply address <CONTROL_LOCAL_PART>-<cookie>@<domain> (default secretary-…), whose cookie is a random 128-bit identifier. It never quotes the held message, since a challenge to a forged sender would otherwise deliver the spam for the spammer. It shows only an 8-character hint of the subject (SUBJECT_HINT_LENGTH) and the sender’s display name, and not even those to a sender that did not pass SPF or DMARC (challenged only under REQUIRE_AUTHENTICATED = no).

The text comes from MESSAGE_<LANG> in the stage’s own section (a user’s own, through the settings layer) or the secretary-challenge.<lang>.body template, per language, with a built-in English fallback; the fields are SENDER_NAME, RECIPIENT, SUBJECT_HINT, ORIGINAL_DATE, DEADLINE, REPLY_ADDRESS and PENALTY. The language is chosen, and the two-space rule applied, as in pepsi-stage-vacation. The challenge and the confirmation notice ship in the same ten languages as every other notice (English, German, Spanish, French, Hungarian, Italian, Russian, Swedish, Turkish and Ukrainian), and so do their subject lines: a SUBJECT_<LANG> option wins, then the shipped subject for the language the text was chosen in, then SUBJECT. An explicit SUBJECT switches the shipped translations off, because an operator who wrote their own subject wants it in every language for which they did not also write a SUBJECT_<LANG>.

A reply to the address confirms when it comes from the challenged address (its envelope sender or From:). A null-sender reply means the challenge bounced, and releases the held mail to the timeout path at once; a reply marked as automatic (an out-of-office) is ignored. A reply after the deadline has no effect: the challenge is gone. The reply itself is always consumed.

58.4. Placement

After pepsi-stage-detect-language and pepsi-stage-check-whitelist, before pepsi-stage-aliases, the list router and local delivery. Run pepsi-stage-auto-whitelist into the same WHITELIST_NAME on the outbound path so the people your users write to are never challenged. pepsi-setup’s wizard wires all of it when asked “Ask unknown senders to confirm by reply”.

58.5. Configuration

[stage-<name>]: PROGRAM = pepsi-stage-secretary, NEXT_STAGE and RESPONSE_STAGE (mandatory), WHITELIST_NAME (mandatory, one name or a {login}/{localpart} template; the operator may name any whitelist, a shared one included, while a value that an account owner sets by mail must stay in their <login>/... namespace or be the operator’s; pepsi-stage-edit-settings enforces this when it stores the value), BOUNCE_STAGE, UNCHALLENGEABLE_STAGE, CONTROL_LOCAL_PART, HOLD_TIME, REQUIRE_AUTHENTICATED, MAX_CHALLENGES_PER_SENDER, DKIM_REQUIRED, CONFIRM_NOTICE, PENALTY, SUBJECT_HINT_LENGTH, TEMPLATE, SUBJECT, DEFAULT_LANGUAGE, the MESSAGE_<LANG>/SUBJECT_<LANG>/CONFIRM_MESSAGE_<LANG> overrides and the locality options. pepsi-setup rejects unresolvable targets and a DEFAULT_LANGUAGE with no text, and warns when no check-whitelist consults the whitelist, no auto-whitelist writes it, CONTROL_LOCAL_PART is a login or an alias, or proof-of-origin is switched off. See pepsi-stage-secretary(1) and Configuration.

58.6. State

  • Inputs: state.spam, state.local_origin, state.auth (SPF, DMARC, DKIM, ARC), state.language; the whole message of a null-sender row, for its Pepsi-Origin proof.

  • Outputs: state.secretary on a held row (challenge, deadline, whitelist; then confirmed or abandoned), state.secretary.unchallengeable on mail routed to UNCHALLENGEABLE_STAGE, and state.spam = false on released mail. The timeout path removes state.secretary. state.dsn is preserved.

  • Transitions: advance to NEXT_STAGE; pause while held; reroute to UNCHALLENGEABLE_STAGE or BOUNCE_STAGE; delete a reply, or timed-out mail when there is no BOUNCE_STAGE.

58.7. Database

pepsi.secretary_challenge (one open challenge per whitelist and sender, deleted when it is answered, bounces or expires) and pepsi.secretary_sent (when each challenge was sent, without its cookie, for the daily cap). A confirmation writes an ordinary pepsi.whitelist row, escaped and anchored exactly as pepsi-stage-auto-whitelist writes one. Under DKIM_REQUIRED = auto (the default) the row demands dkim_required when a held message passed DKIM, and otherwise dmarc_required when one passed DMARC (an aligned SPF pass suffices), recorded per challenge in dkim_seen / dmarc_seen; only when neither passed is it written without a requirement.

58.8. Security

A challenge goes to an envelope sender that nobody has verified, so the stage must meet the backscatter claims of A remote sender and the per-sender rate of Availability (MAX_CHALLENGES_PER_SENDER). Against backscatter it relies on the RFC 3834 and authentication-failure rules, REQUIRE_AUTHENTICATED and quoting nothing of the held message. Every option but NEXT_STAGE and BOUNCE_STAGE is per-address overridable; what a user may set by e-mail is bounded as Per-address settings are a trust boundary describes, WHITELIST_NAME additionally to their own namespace.

58.9. See also

pepsi-stage-check-whitelist, pepsi-stage-auto-whitelist, pepsi-stage-anti-spam, pepsi-whitelist, pepsi-settings, Supported Features, pepsi-stage-secretary(1).