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.4.1. Secure-link messages¶
If a recipient has no key and you asked for encryption, the server may keep your message and send the recipient a link instead. You receive a PIN, which you pass to the recipient by phone, text message or in person, never in the same e-mail. The recipient opens the link, enters the PIN and reads the message in a browser, and may be able to reply there. The link stops working after a few days (seven by default). The stored message cannot be read without the PIN, but our server saw it when you sent it, as with every other message.
Administrator
The keywords are pepsi-stage-encrypt’s
SUBJECT_KEYWORDS_SIGN, _ENCRYPT, _BOTH and _CLEAR_OK.
What [encrypt] does without a key is ON_NO_KEY. The secure-link
portal is The secure-link fallback portal, with SECURE_LINK_STAGE and
pepsi-stage-secure-link. NOTIFY_CLEARTEXT = author
tells a user about every copy that left unencrypted.
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:
statusLists your keys and whether they are published.
generateCreates a key for your address on the server.
registerRegisters 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 FPRPublishes a key so that correspondents can find it, or retires one.
pin FPR CODERecords 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 removeSets up, confirms or removes a second factor (a code from an authenticator app). Once one is set up, every command but
statusneeds 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:
balanceShows 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 lunchAsks 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.orgto post to the list;write to
team-join@example.orgto subscribe, andteam-leave@example.orgto unsubscribe. The server sends a confirmation request; reply to it, or open its link, to complete the step;write to
team-request@example.orgwith commands in the body (helplists them;whoshows the members where the list allows it);write to
team-owner@example.orgto reach the people who run the list.
The lists also have web pages:
/listslists 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/mea 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/securityregisters 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”.