9. Using Pepsi: a guide for users

This chapter is for the people who send and read mail through a Pepsi server, not for the people who run it. It collects in one place everything a user can see or do: setting up a mail program, the words that Pepsi adds to subject lines and the ones that a user can add, the extensions for mail programs, changing personal settings by e-mail, the certificate from the organisation, the GNU Taler wallet, mailing lists, and the web pages for users. Each section ends with a note for the administrator. The note says what must be switched on for the feature to exist and which chapter describes it. The section on protection comes first, because it is the one users most often get wrong.

You may copy this chapter, as it is or changed, into your own help pages or a welcome message, under the same terms as the rest of this manual. The examples use example.org. Replace it with your own domain, and leave out the sections on features your server does not have.

Note

For the administrator, before you copy it. Do not describe this service as “end-to-end encryption”. With keys held by the server, the ends are the servers, not the people (Gateway custody (custody = local, the MTA key)). Check the wording of the tags and keywords below against your configuration ([stage-decrypt] TAG_*, [pepsi-ingress] TAG_EXTERNAL, [stage-encrypt] SUBJECT_KEYWORDS_*), and keep the paragraph on stored mail that fits your pipeline. The exact meaning of every indicator is in What a security indicator means. The section on protection says the same in fewer words and claims no more. Studies of encryption tools find that users who misjudge what protects them make worse choices than users who were told nothing (Users and vendor claims misrepresent what end-to-end encryption protects). This text has not been tested with users, so watch which questions your users ask and adjust it.

9.1. What the mail server does for you

Our mail server encrypts and decrypts mail for you. When someone sends you an encrypted message, the server opens it before it reaches your mailbox. When you write to someone whose key the server can find, it encrypts your message before it leaves. You do not need to install anything for this.

This protects your mail on its way between mail servers: someone listening on the network, or a server that it passes through, sees only scrambled text. It does not hide your mail from this server or from the people who run it. The server holds the keys and reads your mail to encrypt and decrypt it. That is why we do not call it “end-to-end encryption”.

The server also checks where incoming mail really comes from, and can hold back mail from strangers until they pay a small fee or confirm that they are human (Mail from strangers, and your GNU Taler wallet).

9.1.1. Your mailbox

(Administrator: keep the paragraph that fits your server.)

Without your own key: the messages in your mailbox are stored as ordinary, readable mail, including the ones that arrived encrypted. Anyone who gets access to your mailbox, or to the server’s storage, can read them.

With your own key in your mail program: mail that the server opened for you is encrypted again to your own key before it is stored, so only your mail program can read the stored copy. If you lose every copy of that key, you lose those messages. To be safe, register a second key, for example on another device or as a backup. Mail that arrived unencrypted is stored as it arrived.

9.1.2. When in doubt

If a message asks for money, passwords or urgent action, check with the sender by phone or in person, whatever its tags say.

Administrator

Encryption and decryption are pepsi-stage-encrypt and pepsi-stage-decrypt, set up by pepsi-setup --wizard when you answer yes to encryption; Key management explains the keys. Re-encrypting stored mail to the user’s own key is pepsi-stage-reencrypt. What all of it protects against is in Threat model.

9.2. Setting up your mail program

In most mail programs you only need to enter your e-mail address and your password. The program then asks our server for the rest: the server names, the ports and the kind of connection security. Thunderbird does this, and so do other programs that follow the same convention. If your program asks for the settings anyway, use the ones that your administrator gives you. As your user name, give your whole e-mail address unless you were told otherwise.

Our server sends your mail out (the “outgoing” or SMTP server). Your mailbox is read through a separate program (the “incoming” or IMAP server), which may have a different name.

Administrator

Autoconfiguration is served by pepsi-httpd (Mail client autoconfiguration). It needs [pepsi-autoconfig] IMAP_HOST or POP3_HOST, because Pepsi does not serve mailboxes itself. Until one of them is set, nothing is published. It also needs an autoconfig.<domain> DNS record and a certificate that covers that name. The outgoing half is taken from the submission listener and needs no setting.

9.3. Words in the subject of mail you receive

Some messages arrive with a word in square brackets at the start of the subject. The server adds them; senders cannot fake them, because the server removes look-alikes that they put there. A banner that looks similar inside the message text proves nothing, because anyone can type it.

[decrypted]

The message arrived encrypted, and our server opened it. It was protected on the way here. It does not tell you who sent it: anyone can encrypt a message to you. It also does not mean the message stayed private on the sender’s side.

[decrypted, unauthenticated]

Like [decrypted], but the kind of encryption that it arrived in cannot detect changes, and nobody signed it, so it may have been altered on the way. Be careful with links and requests in it.

[verified: alice@example.org]

The message was signed with a key that belongs to that address, and the signature checks out. You can trust that the text came from that address and was not changed. It does not tell you that the person behind the address is who they claim to be, or that they are entitled to ask you for anything. A familiar-looking address may still belong to a stranger, so read the address in the tag, not just the name.

[verified (except reply-to): alice@example.org]

Like [verified], but a mailing list added a “reply to” address that the signer did not sign. Your reply may go to the list, not to the signer.

[unverified signer]

The message was encrypted and signed, but the server could not confirm whose key made the signature. Treat it like an unsigned message.

[bad signature]

The message was encrypted, and the signature on it does not match its content. Someone may have changed it or replayed it. Do not act on it without checking with the sender another way.

[unsigned, usually signed]

Mail from this sender has carried a valid signature recently, but this message has none. It may be a forgery, or the sender may simply have written from another device. Your server shows this tag only if the administrator turned it on.

[external]

The message claims to come from one of our addresses, but it came from outside and nothing proved the claim, or the sender’s own domain says it did not send it. It may be forged. It is not a spam verdict, and most mail from outside carries no tag at all.

[!LANG] (at the end of the subject)

The message is in a language that your language filter would refuse, and the filter is set to mark such mail rather than return it (Changing your settings by e-mail).

[VACATION] (at the end of the subject)

The message arrived while you are marked as away (below). The sender was sent your out-of-office notice, unless they received one recently.

No tag says nothing good or bad: most mail is neither encrypted nor signed. The absence of [external] does not prove a message is genuine.

Pepsi removes its own tags from the subject when you reply, so your correspondent does not see them. The server also records its verdict in a header field (X-Pepsi-Crypto), which the extensions for mail programs show in a place that the sender cannot imitate (Mail program extensions).

Administrator

The crypto tags come from pepsi-stage-decrypt (TAG_*, SUBJECT_TAGS, ON_MISSING_SIGNATURE = tag for [unsigned, usually signed]), [external] from pepsi-ingress (EXTERNAL_SUBJECT_TAG, TAG_EXTERNAL), [!LANG] from pepsi-stage-block-language under ENFORCEMENT = soft and [VACATION] from pepsi-stage-vacation. What a security indicator means states exactly what each tag promises; Indicator tags do not leave the deployment describes how the tags are removed from replies.

9.4. Words you can put in the subject of mail you send

By default, a message you send is encrypted when the server finds a key for every recipient. If it does not find one, the message usually leaves unencrypted, and nothing in your mail program shows the difference. A reply to an encrypted message is no exception. To ask for more, put one of these words anywhere in the subject. The server acts on it and removes it before the message leaves, so the recipient never sees it.

[encrypt]

Never send this message unencrypted. If a recipient has no key, the message goes to them as a secure link (below) or comes back to you undelivered, depending on the server’s setup.

[sign]

Sign the message with your key, so the recipient can check that it came from you and was not changed.

[secure]

Both: encrypt and sign.

[clear-ok]

Send it even though the recipient’s key could not be looked up because their domain’s DNS is failing. Without this word, the server waits and retries rather than send in the clear when that happens.

If you misspell one of these words, for example [encyrpt], the server writes back and names the word it expected.

9.5. Mail program extensions

Subject tags are visible everywhere, but a message body can contain a banner that looks like one. Two extensions for mail programs show the server’s verdict in a part of the window that the message itself cannot reach:

Thunderbird. The Pepsi gateway verdict extension adds a Gateway button to the message toolbar. Its badge shows a green tick for verified mail, a blue dot for decrypted mail, an amber question mark when something could not be checked and a red mark for a bad signature or a warning, such as a sender whose display name contains a different address. Clicking the button explains the verdict. No badge means the server said nothing about the message, which is neither good nor bad.

Outlook. The Pepsi add-in has two panes. Gateway verdict, opened from the ribbon while reading, shows the same verdict as the Thunderbird button. Protect message, opened while writing, asks for signing and encryption, as the subject words above do.

Neither extension sends anything anywhere: it reads header fields of the message inside your mail program. Other mail programs, webmail and phones show the subject tags only.

Whatever extension you use, set your mail program to block remote content (pictures loaded from the Internet) in all mail; Remote content says where the setting is in each common program.

Administrator

Mail client extensions describes both extensions, what each verdict shows and how to install them. The Thunderbird extension is installed from the .xpi that make thunderbird-xpi builds, and an enterprise policy can roll it out. The Outlook add-in needs [pepsi-httpd] ADDIN = yes and is sideloaded from /addin/manifest.xml (The Outlook add-in). The verdicts can be trusted only where the managed domains accept mail from Pepsi alone.

9.6. Changing your settings by e-mail

You can change some of the server’s behaviour for your own address by sending an e-mail. Send it from your own account, through our server, to pepsi@example.org with the subject Pepsi. The body lists the settings to change, one per line, under the name of the part of the server that they belong to. Greetings and a signature are ignored.

The server checks the whole request. If everything is valid, it adopts the change and replies with all your settings. Otherwise it changes nothing and replies with what was wrong. An empty message simply returns your current settings, which is the best way to start, since it shows which parts you may change and their exact names. To return a setting to the server’s default, send it with nothing after the =. If the message has other recipients too, they get it as usual.

Which settings you may change is the administrator’s choice. Typical ones:

Blocking remote content. Many messages, newsletters above all, contain tiny invisible pictures that your mail program fetches from the sender’s server when you open the message. The fetch tells the sender that you read it, when, and roughly where. To have the server remove everything that a message would fetch by itself:

[stage-defang]
DEFANG = on

Pictures sent as part of the message stay, and links still work: nothing happens until you click one. Some messages will look plainer. A message that was changed this way carries the line X-Pepsi-Warning: remote-content-defanged in its header. Signed messages are never changed, since that would break their signature, so keep your mail program’s own setting to block remote content as well. DEFANG = off turns it off again.

Languages. The server can recognise the language a message is written in, and refuse or mark mail in languages you do not read. To accept English and German, refuse French, and mark refused mail with [!LANG] rather than return it to the sender:

[stage-block-language]
WHITELIST = en, de
BLACKLIST = fr
ENFORCEMENT = soft

With ENFORCEMENT = hard the sender gets the message back instead. The server recognises only the languages that your administrator enabled. It writes its own answers to you, and to people who write to you, in the language of the message being answered where it can.

Out of office. To be away from 1 to 14 August, with an emergency contact and your own notice for German-speaking senders:

[stage-vacation]
VACATION_RANGES = 2026-08-01:2026-08-14
EMERGENCY_CONTACT = colleague@example.org
MESSAGE_DE = Ich bin bis zum 14. August nicht im Büro.

Each correspondent gets one notice a week at most. Mailing lists, automatic mail and bounces are never answered. Senders in other languages get the server’s standard notice in their own language. 2026-12-24: (with no end date) means “until further notice”; VACATION_RANGES = with no dates ends it.

Unknown senders. Where the server holds back mail from strangers (Mail from strangers, and your GNU Taler wallet), the administrator may let you adjust that too. The empty-message reply shows what you may change.

Administrator

The settings editor is pepsi-stage-edit-settings, offered by pepsi-setup --wizard. It must sit on the submission path. Only the stages in EDITABLE_STAGES can be changed. The wizard lists the inbound filters that it wired (check-whitelist, block-language, secretary, anti-spam, vacation, defang). Which stages are safe to list is Per-address settings are a trust boundary. An operator sets the same overrides with pepsi-settings, and Configuration explains how they layer over the configuration file. Language detection is pepsi-stage-detect-language (its LANGUAGES option limits which languages it can recognise). The filter is pepsi-stage-block-language and the out-of-office notice pepsi-stage-vacation, whose default texts ship in ten languages.

9.6.1. Your keys by e-mail

A separate address, pepsi-keys@example.org, manages the keys that the server holds for you. The command is the subject of the message, again sent from your own account:

status

Lists your keys and whether they are published.

generate

Creates a key for your address on the server.

register

Registers the key of your own mail program, taken from the message (its Autocrypt: header or an attached key). Mail kept for you is then encrypted to that key, and only your mail program can read it.

publish [FPR], retire FPR

Publishes a key so that correspondents can find it, or retires one.

pin FPR CODE

Records that you compared a correspondent’s key fingerprint with them in person. Every user of the server then trusts that key.

otp enroll, otp confirm CODE, otp remove

Sets up, confirms or removes a second factor (a code from an authenticator app). Once one is set up, every command but status needs the current code in the subject, so a stolen password alone cannot change your keys.

The server refuses commands in a reply or a forward (Re:, Fwd:), since someone else may have written them.

Administrator

The key commands need [stage-encrypt] RESPONSE_STAGE and are named by KEYS_CONTROL_LOCAL_PART (pepsi-stage-encrypt). The commands and the second factor are described in Key management, A user’s own pin and A second factor for key management.

9.7. A certificate from the organisation

(Administrator: keep this section only if the server orders certificates for your domain from a certificate authority.)

The organisation gives each of its users a certificate from a certificate authority, a company that confirms to everybody else who a mail address belongs to. Mail programs accept such a certificate without a warning, so your correspondents can check that a message signed with it really comes from you, and they can encrypt their replies to you.

You do not have to do anything to get it. When you send your first message through the server, the server asks the certificate authority for a certificate for you. That first message goes out at once, the way your mail goes out now: unsigned, or signed with a key that the server already holds for you. The certificate usually arrives within minutes, or later when somebody at the organisation first has to confirm your name. From then on, the server uses it whenever it signs a message of yours in the S/MIME format, and it renews the certificate before it expires.

The certificate carries your given name and surname, as the organisation’s directory has them, or as your mail program shows them as the sender of your first message. When the name comes from your mail program, an administrator usually checks it first. If the name is wrong, tell an administrator, who can correct it; a certificate that was already issued keeps the old name until it is renewed.

You cannot turn the certificate off yourself. If you do not want one, ask an administrator, who can opt you out. That revokes the certificate: your correspondents’ mail programs can then see that it is no longer valid, and the messages that they encrypted to you before stay readable. The same happens when you leave the organisation.

Administrator

This is the managed PKI of Certificates from a commercial CA: the managed PKI, set up per domain with pepsi-keys mpki domain set and its other commands (pepsi-keys(1)). Whether a message is signed, and in which format, is decided by [stage-encrypt] SIGN and PREFER: under the defaults, cleartext mail is signed only on request, and in OpenPGP when the user also has an OpenPGP key. Names taken from a display name wait for your approval unless the domain trusts them (--header-names). Opting a user out is pepsi-keys mpki user set ADDRESS --select no; what the certificate protects, and what it does not, is in Certificates from a commercial CA.

9.8. When the first message from someone new arrives late

Your server may ask the sending server to try again later when someone writes to you for the first time (“greylisting”). A real mail server tries again after a few minutes and the message arrives then; software that sends spam often does not. From then on, mail from that sender arrives at once.

So a first message from a new correspondent, such as a confirmation link or a password reset from a service you have just signed up with, can be late by some minutes, rarely by up to an hour. Mail from the large mail providers, from people you have written to and from addresses on your whitelist is not delayed. To stop the delay for a sender you expect, write to them first, or add the address to your whitelist before the message is sent: on your own web pages (below), or, if you have a login on the server, with pepsi-whitelist add.

Your own web pages also show Deferred mail: the senders whose mail to you had to wait, when they first tried, how often they tried and whether a retry got through. A sender that is still waiting is one whose server has not tried again yet; most of these never do, because they send spam. If you see a sender you know there, choose Allow this sender. The address then goes on your whitelist, and mail from it is not delayed again. The whitelist counts only for mail that the sender’s domain authenticates, so somebody who forges that address in a message gains nothing by it. You can also type an address there before the sender writes to you. You cannot see what was deferred for other people, and nothing that you allow there affects their mail.

Administrator

Greylisting is pepsi-greylist, off unless you turn it on. Its whitelist bypass reads the whitelists that pepsi-stage-check-whitelist consults, so a user’s own list ({localpart}/correspondents) counts when a stage names it. pepsi-greylist allow lets a sender, domain or network through for every user; Greylisting says what to watch. The Deferred mail page is the console’s (Greylisting) and needs sign-in by e-mail (Signing in by e-mail). Its Allow this sender writes to the first whitelist of the user’s own (<login>/…) that the bypass consults; when the bypass consults only shared whitelists, or WHITELIST_BYPASS is off, the page offers no such button, so name a per-user whitelist in [pepsi-greylist] WHITELIST_NAME or in a whitelist stage.

9.9. Mail from strangers, and your GNU Taler wallet

Your server may hold back mail from senders it does not know, in one of two ways:

  • Pay to send. The sender is asked to attach a tiny payment with GNU Taler before the message reaches you. A real correspondent pays a few cents once. Anybody sending millions of messages pays millions of times.

  • Confirm to send. The sender is asked to reply once to prove that a person is behind the address.

Either way, people you have written to are never asked: the server remembers your correspondents. Mail that the sender does not pay for or confirm in time is returned to them or dropped, depending on the server’s setup.

The other side works for you too. When you write to someone whose server asks for payment, your server can pay automatically from a wallet, within limits per message and per day that the administrator sets. Payment happens only for messages that provably came from you, and the message is then delivered as if nothing happened.

9.9.1. Your wallet by e-mail

Send a message from your own account to pepsi-wallet@example.org. The command is the subject, and the server replies. If the message has other recipients too, they get it as usual. The commands are:

balance

Shows how much money the wallet holds.

withdraw EUR:25 https://exchange.example.org/

Tops up the wallet from the named GNU Taler exchange. The reply gives the bank transfer details.

pull EUR:5 lunch

Asks someone for money. The reply contains a link to forward to them.

push taler://pay-push/…

Accepts a payment someone sent you; the link may also be in the body.

If the exchange needs to identify you first (a legal requirement for larger amounts), the reply contains the link where you do so. A request the server cannot read is answered with these instructions.

Administrator

Pay to send is pepsi-stage-anti-spam (with a GNU Taler merchant backend, set up by pepsi-setup), confirm to send is pepsi-stage-secretary, and your users’ correspondents are remembered by pepsi-stage-auto-whitelist and pepsi-stage-check-whitelist. A user with a login on the host can manage their own list with pepsi-whitelist. Automatic payment and the wallet commands are pepsi-stage-auto-pay (MAX_TOTAL, MAX_TOTAL_PER_DAY, WALLET_MODE; the wallet commands need RESPONSE_STAGE on a submission-path section). The payment headers are in SMTP Protocol Extensions.

9.10. Mailing lists

A mailing list on our server answers on several addresses. For a list team@example.org:

  • write to team@example.org to post to the list;

  • write to team-join@example.org to subscribe, and team-leave@example.org to unsubscribe. The server sends a confirmation request; reply to it, or open its link, to complete the step;

  • write to team-request@example.org with commands in the body (help lists them; who shows the members where the list allows it);

  • write to team-owner@example.org to reach the people who run the list.

The lists also have web pages:

  • /lists lists the advertised lists. Each list’s page shows its description, the subscription forms and, where the list allows it, a link to its archive. Archive pages hide the senders’ addresses from visitors who are not signed in.

  • Under /lists/me a member signed in with a list account sees their subscriptions and delivery preferences on every list, and which level each preference comes from. /lists/me/security registers security keys (for example a USB key) as a second factor for that account.

  • List owners and moderators approve held messages and subscription requests under /lists/<list>/admin, and owners change the list’s settings there.

Administrator

The list system is described in Mailing lists, the mail commands in pepsi-stage-list-command and the archive in Archives. The web pages need LISTS = yes on an HTTPS listener (Three listener flags, and two of them have opposite advice) and are described in The public mailing-list pages. Account registration on the web is [pepsi-list] WEB_REGISTRATION. The web pages mail nothing yet (the web tier sends no mail of its own). Until they do, tell users to subscribe by e-mail, or pass the confirmation links on yourself.

9.11. Your own web pages

Besides the list pages, the server can offer you a web page about your own address. On the sign-in page, choose to sign in with a link sent to your e-mail address. Enter your address and open the link the server mails you. Opening the link changes nothing; you confirm on the page that it shows, with your second-factor code or security key if you set one up. The link works once and for half an hour.

There you can see the keys the server holds for you and the keys it knows for your correspondents, the log of mail you sent and received, and the mail that greylisting deferred (above). You can also ask for a new key, register your own, publish or withdraw one, ask for a certificate for S/MIME, or allow a sender whose mail was deferred. You cannot see anybody else’s address there. Your settings are still changed by e-mail (above).

The secure-link pages, where a recipient reads a message sent as a secure link, need no account: the link and the PIN are all a recipient needs. The administration console and the secure-link portal follow your browser’s language, in one of ten languages. The mailing-list pages are available in English, German and French.

Administrator

Sign-in by e-mail is Signing in by e-mail. It needs [pepsi-admin] ENROL_STAGE and ENROL_URL (an ADMIN = yes listener the users can reach), the pepsi-httpd-admin package and [pepsi-admin] CONFIG_DB. The pages are the console’s end-user pages (The administration console); what the mechanism protects is Signing in to the console by e-mail. The portal is The secure-link fallback portal. The pages’ languages are discussed in The administration console under “The interfaces’ languages”.