19. Microsoft Exchange as a gateway

Pepsi can sit in front of and behind a Microsoft Exchange or Exchange Online deployment as a transparent crypto gateway: inbound mail is decrypted and verified before Exchange stores it, outbound mail is signed and encrypted after Exchange has sent it. Users get S/MIME and OpenPGP without touching their clients.

Warning

Only the tenant proof (Exchange Online: the tenant proof) rests on measurements against a real Exchange Online tenant. The rest of this chapter has not been tested against a real Exchange or Exchange Online tenant: Pepsi’s own test suite uses a plain SMTP stand-in and .invalid domains. The connector settings below follow Microsoft’s documented behaviour, but expect to adjust them, and read Troubleshooting before concluding that Pepsi is at fault.

19.1. Topologies

Three arrangements are supported. The one that you choose decides what you configure in the rest of this chapter.

Both directions (the full gateway). One Pepsi instance is the organisation’s MX and the smarthost that Exchange sends through. This is the arrangement that gives end-to-end crypto in both directions.

Internet ──▶ pepsi-ingress :25 ──▶ arc ──▶ decrypt ──▶ autocrypt-learn
             ──▶ aliases ──▶ route ──┬─▶ exchange (smarthost)
                                     └─▶ internet (direct MX)

Exchange ──▶ pepsi-ingress :587 ──▶ encrypt ──▶ srs ──▶ dkim-sign ──▶ internet
             (authenticated)

pepsi-stage-autocrypt-learn follows decrypt because it needs the plaintext. This stage learns correspondents’ keys from inbound mail: from their Autocrypt: header, attached keys and S/MIME certificates, and from the Autocrypt-Gossip: of a message that arrived encrypted. These keys give the outbound encrypt stage keys to encrypt to without asking the network. The stage also records the proof that a correspondent holds one of our keys, because they sent mail encrypted to it and signed by them; that record stops ATTACH_KEYS_AS_FILES from attaching our key file to mail for them. If you leave the stage out, you lose both.

Front-only. Pepsi is the MX and hands everything to Exchange; Exchange’s own outbound path is left alone. Inbound mail is decrypted and verified; outbound mail is untouched. This is a realistic choice for an organisation that cannot change its outbound flow.

Behind-only. Exchange keeps the MX; Pepsi is only the smarthost that Exchange relays through. Outbound mail is signed and encrypted; inbound is untouched. This suits an organisation whose inbound already passes through a compliance or filtering gateway.

The two partial cases are not second-class: the routing stage, the loop prevention and the ADDRESS_FAMILY control all behave the same in each. What differs is only which half of the pipeline you configure.

19.2. The routing decision

A gateway in front of another mail system has to make one routing decision for every inbound message: does this recipient belong to the system behind me, or to the internet?

Getting it wrong causes not a failed delivery but a loop. The domains behind the gateway are exactly the domains whose public MX is the gateway, so handing a message for one of them to a direct-to-MX relay posts the message back into Pepsi’s own ingress, which accepts it, relays it out again, and repeats.

pepsi-stage-route exists for this decision:

[stage-route]
PROGRAM = pepsi-stage-route
# Recipients at a domain we serve go to Exchange...
MANAGED_STAGE = exchange
# ...everything else out to the public internet.
NEXT_STAGE = internet

MANAGED_DOMAINS defaults to [pepsi-ingress] ACCEPTED_DOMAINS, so the set of domains treated as “behind the gateway” cannot drift from the set ingress accepts. Add ROUTES only for exceptions, such as a legacy subdomain that is delivered locally or a partner domain with its own next hop.

Tell Pepsi how to find out whether an address exists in Exchange. Then pepsi-ingress can refuse an unknown one while the sender is still connected, instead of accepting it and having Exchange bounce it later. Such a bounce goes to the envelope sender, which spam forges (see A remote sender). RECIPIENT_CHECK = probe asks Exchange with RCPT TO and no message. That only helps where Exchange itself refuses unknown recipients at RCPT: on-premises with recipient filtering, or Exchange Online with Directory-Based Edge Blocking. Otherwise export the valid addresses to a file and use RECIPIENT_CHECK = map:

[stage-route]
PROGRAM = pepsi-stage-route
MANAGED_STAGE = exchange
NEXT_STAGE = internet
RECIPIENT_CHECK = probe
PROBE_HOST = example-com.mail.protection.outlook.com
# or: RECIPIENT_CHECK = map
#     RECIPIENT_MAP = /etc/pepsi/exchange-recipients

Without either, every address at the managed domains is accepted, and pepsi-setup run says so.

In a behind-only deployment there is no routing decision to make: Pepsi only ever relays outward, and the routing stage is not needed.

19.3. Exchange Online: the tenant endpoint

Important

Point the smarthost at the tenant-specific endpoint, never at your own domain’s public MX.

Your domain’s MX record points at Pepsi (that is the point of the gateway). A smarthost set to example-com.mail.protection.outlook.com reaches Microsoft; a smarthost set to mail.example.com reaches Pepsi, and every message loops.

The tenant endpoint is shown in the Microsoft 365 admin centre under the domain’s DNS records. It has the form <tenant>.mail.protection.outlook.com, where <tenant> is normally your domain with the dots replaced by hyphens (example.com → example-com). Regional tenants may differ (for instance <tenant>-ch.mail.protection.outlook.com), so use the name that the admin centre shows rather than one that you construct yourself.

[pepsi-stage-relay-to-smarthost-mta-exchange]
HOST = example-com.mail.protection.outlook.com
PORT = 25
MODE = starttls
TLS_VERIFY = yes
AUTH = none
DOMAINS = example.com example.net
# Exchange Online rejects a sending IPv6 address with no PTR; see below.
ADDRESS_FAMILY = ipv4

AUTH = none is correct here: Exchange Online authenticates an inbound connector by the sending IP address or by the TLS certificate, not by SASL. Pepsi still uses STARTTLS, which Exchange Online requires.

pepsi-setup refuses a smarthost whose host is this machine and whose port is one that an ingress listener is bound to, so the most direct form of this mistake is caught before it can loop.

Important

The smarthost covers only the way in. For the way out, an Exchange Online tenant needs the tenant proof (Exchange Online: the tenant proof): a [pepsi-ingress-exchange-online-<name>] section with your tenant id, and DKIM signing for your domains in Microsoft 365. Without it Pepsi refuses every message that Exchange Online’s outbound connector sends through it to another domain, because Microsoft 365 customers all send from the same addresses and nothing else tells your tenant from theirs. pepsi-setup --wizard asks for the tenant id as soon as the Exchange host is an Exchange Online endpoint, and pepsi-setup validate warns when a smarthost points at Exchange Online and no section names the tenant. If Exchange Online sends directly instead, publish include:spf.protection.outlook.com in your SPF record and Microsoft’s DKIM selectors.

19.4. Address family selection

Exchange Online rejects mail from a sending IPv6 address whose reverse DNS (PTR) is missing, with a 550 5.7.1 ... S820 error. A dual-stacked host prefers IPv6, so a machine whose IPv4 reverse DNS is correct and whose IPv6 reverse DNS was never delegated delivers fine to everyone except Exchange Online.

The fix is to reach that one destination over IPv4. ADDRESS_FAMILY takes any (the default), ipv4 (also spelled v4/v4only) or ipv6 (v6/v6only).

Precedence is: the ``[…-mta-*]`` entry, then the owning ``[stage-*]`` section, then ``any``. The per-entry level is the one that matters: pinning the whole stage to IPv4 would also force every other destination onto IPv4, including one that publishes only AAAA.

When a delivery is using a family you did not expect, check the MTA entry first, then the stage section, and remember that the configured family is intersected with what the local host can actually route: pinning ipv6 on a host with no global IPv6 route leaves nothing to connect to.

The better fix, where you control the reverse zone, is to publish the PTR record. ADDRESS_FAMILY is for when you do not.

19.5. Loop prevention

A gateway on both sides of another MTA is the classic loop topology, and Pepsi has three independent defences. None of them is optional in this deployment.

1. Configuration refusal (``pepsi-setup``). It makes two checks, and both report an error rather than a warning:

  • A routing stage from which a served domain can reach pepsi-stage-relay-to-internet. pepsi-setup walks forward from every stage that a managed recipient can reach and refuses if a direct-to-MX relay is among them. (BOUNCE_STAGE is not followed: a bounce is a new message with a null sender about a delivery that has already failed, and it legitimately reaches a relay.)

  • A smarthost whose PORT is one that an ingress listener is bound to and whose HOST is this host: its [pepsi-ingress] HOSTNAME, localhost or a loopback address. Both halves are required: a site may legitimately run an unrelated relay on the same host, or reach a different machine on port 25.

2. The hop count (``MAX_HOP_COUNT``). Both relay stages count Received: header fields and refuse to relay a message with more than MAX_HOP_COUNT (default 30, RFC 5321 §6.3). This is the backstop, not the defence: by the time it fires, thirty copies of the message have crossed the gateway, and the bounce it produces is addressed back into the loop.

3. Exchange’s own connector scoping. Restrict the inbound connector to Pepsi’s IP addresses (below), so a message arriving from anywhere else is not treated as gateway traffic.

19.6. Exchange connector configuration

The exact settings depend on whether Exchange sends to Pepsi, receives from Pepsi, or both.

19.6.1. Inbound to Exchange (Pepsi → Exchange)

In Exchange Online this is an inbound connector (Exchange admin centre → Mail flow → Connectors → From: Your organisation’s email server, To: Office 365):

Setting

Value

Connector type

From your organisation’s email server to Office 365

How to identify the sender

By verifying that the sending server’s IP address matches, or, preferably, by the certificate subject name. For the IP address, list every address that Pepsi sends from: see PUBLIC_IP in the relay stage’s own [stage-<name>] section. PUBLIC_IP is a per-stage option, found by PROGRAM, never by a section named after the program.

Reject messages if not sent over TLS

Yes

On on-premises Exchange the equivalent is a Receive Connector on the Hub Transport / Frontend role, with RemoteIPRanges set to Pepsi’s addresses and PermissionGroups including AnonymousUsers (with Ms-Exch-SMTP-Accept-Any-Recipient granted if Exchange must accept for domains it is not authoritative for).

Note

If the connector identifies Pepsi by IP, and Pepsi is pinned to IPv4 for this destination (Address family selection), list the IPv4 address. If you list only the IPv6 address of a host that will never use it, authentication fails silently.

Accept the managed domains only from Pepsi. Everything that Pepsi does on the inbound path applies only to mail that actually passes through it: decryption, signature verification, the [verified] subject tag, SPF/DKIM/DMARC evaluation, and the spam and language gates. The system behind it remains reachable on its own: an Exchange Online tenant’s <tenant>.mail.protection.outlook.com endpoint is public, and an on-premises Exchange often still listens on port 25. A sender who delivers there directly skips every one of those checks, and a message forged to look as if Pepsi had processed it (an X-Pepsi-* header, a [verified] tag) arrives looking exactly like one that was. So the downstream system must refuse mail for the managed domains from anything but Pepsi: in Exchange Online, a partner inbound connector that rejects mail for those domains unless it comes from Pepsi’s addresses or certificate (RestrictDomainsToIPAddresses / RestrictDomainsToCertificate); on premises, a firewall that lets only Pepsi reach the receive connectors, and no anonymous permission on any other connector. The same holds for any MDA or MTA behind Pepsi, not only Exchange.

19.6.2. Outbound from Exchange (Exchange → Pepsi)

How Pepsi recognises Exchange’s outbound mail depends on where Exchange runs. Exchange on premises can log in to Pepsi with an account of its own. Exchange Online cannot: its outbound connector offers neither SMTP AUTH nor a certificate of its own, it delivers to port 25 only, and every Microsoft 365 customer sends from the same Microsoft addresses. Pepsi therefore checks each of its messages for proof that it was sent by your tenant.

19.6.2.1. Exchange Online: the tenant proof

A section [pepsi-ingress-exchange-online-<name>] names your tenant (see pepsi.conf(5)). Mail from Microsoft’s outbound addresses may then name recipients outside your domains on the MX listener, and at the end of the data Pepsi relays it only when all of the following hold:

  • the header carries exactly one X-MS-Exchange-CrossTenant-Id field, and it names your tenant;

  • the From: field names one mailbox, at one of the domains that the section lists;

  • a DKIM signature by that domain verified, which only your tenant can make.

Everything else is refused with 550 5.7.1. The rules are this strict for three reasons, which we measured against a real tenant:

  • Exchange Online writes the sending tenant’s id into every message, but it does not remove a copy that the sender wrote. Another tenant can claim your id, and its message then arrives with two such fields.

  • Microsoft’s DKIM signature does not cover the recipients, so one signed message could be sent again to anybody. Sent through another tenant, it carries that tenant’s id as well, and is refused.

  • The header fields mean something only on mail that really comes from Exchange Online, so Pepsi asks for the proof only from Microsoft’s published outbound addresses (SENDER_NETWORKS).

To set it up:

  1. Sign your domain’s mail in Microsoft 365. In the Microsoft Defender portal (Email & collaboration → Policies → Email authentication settings → DKIM), create the keys for your domain, publish the two CNAME records that the portal shows (selector1._domainkey and selector2._domainkey), then switch signing on. In PowerShell:

    Set-DkimSigningConfig -Identity example.com -Enabled $true
    Get-DkimSigningConfig -Identity example.com | Format-List Enabled,Status
    
  2. Name the tenant in Pepsi. The tenant id is shown in the Microsoft Entra admin centre under Overview:

    [pepsi-ingress-exchange-online-example]
    TENANT_ID = 00000000-0000-0000-0000-000000000000
    DOMAINS = example.com
    

    Every domain in DOMAINS must also be in [pepsi-ingress] ACCEPTED_DOMAINS. Restart pepsi-ingress after the change.

  3. Route Exchange’s outbound mail through Pepsi. In the Exchange admin centre, add a connector from Office 365 to Partner organisation, used for mail to all domains, that routes through the smart host named by Pepsi’s MX host name and always uses TLS with a certificate that a trusted CA issued for that name. In PowerShell:

    New-OutboundConnector -Name "Pepsi" -ConnectorType Partner `
      -RecipientDomains * -UseMXRecord $false -SmartHosts mail.example.com `
      -TlsSettings DomainValidation -TlsDomain mail.example.com
    

    Check first that no transport rule sends the same mail to another connector: a rule with the action Use the following connector wins over the connector’s own scope.

  4. Test with one domain first. Give the connector a single test recipient domain (-RecipientDomains) before you widen it to *. The journal of pepsi-ingress names the tenant of every relayed message (relaying outbound mail of Exchange Online tenant) and gives the reason for every refusal (not proven to come from a configured Exchange Online tenant).

A message that a mailbox rule in your tenant forwards for an outside sender carries no signature by your domain, and is refused. Pepsi relays no mail that it cannot prove to be your tenant’s.

19.6.2.2. Exchange on premises: an account of its own

On premises, Exchange sends through a Send Connector to a submission listener and authenticates there:

[pepsi-ingress-listener-submission]
SERVE = tcp
BIND_TO = 0.0.0.0
PORT = 587
MODE = starttls
SUBMISSION = yes
SASL_TYPE = dovecot
SASL_PATH = /run/dovecot/auth-client

There are two ways to let it relay through Pepsi, and they are not equivalent.

SASL with a dedicated account (recommended). Exchange authenticates with a username and password. A submission listener enforces RFC 6409 §6: a sender may only use an address that the authenticated identity is entitled to. The connector’s account therefore needs a USERNAME_MAP entry that permits the served domains, or every message that Exchange relays is refused:

# /etc/pepsi/username.map — the connector account may send as any of our users.
exchange-connector:   *@example.com *@example.net

Without that entry the account may send only as itself, and the first message that Exchange relays gets a 550.

Network trust (``MYNETWORKS``). This is simpler, because you list Exchange’s addresses and skip authentication, but it carries the self-relay risk that this chapter is about: any host that can reach the listener from a trusted address can relay through it, and a mistake in the range turns Pepsi into an open relay. A trusted network may also send as any address unless SENDER_MAP binds the addresses that it may use. The same file binds the addresses of a client certificate, which may send as nothing until the file binds them. Prefer SASL; if you use MYNETWORKS, list individual addresses rather than ranges, bind them with SENDER_MAP, and never include loopback. A range bound to a bare * lets every machine in it, including other tenants of a shared cloud range, send mail that Pepsi signs as any of your addresses (the EchoSpoofing configuration); pepsi-ingress and pepsi-setup validate warn about each such range. Never list Microsoft’s Exchange Online addresses there; use the tenant proof above instead. A local shell user states what the submission identity does and does not protect.

19.7. The Outlook add-in

Pepsi’s encryption stage acts on two headers that a message can carry: X-Pepsi-Sign and X-Pepsi-Encrypt. The add-in is what lets a user set them from Outlook (its Protect message pane, while composing). The same add-in carries a second pane for mail the user receives: Gateway verdict shows what the decrypt stage recorded in X-Pepsi-Crypto and X-Pepsi-Warning in Outlook’s own task pane, outside the message area. Mail client extensions describes what the pane shows, what it proves and which Outlook versions carry it; the deployment below covers both panes.

Enable the routes and reload pepsi-httpd:

[pepsi-httpd]
ADDIN = yes
# Only needed when the request's own Host header does not name this gateway
# (for example behind a proxy that rewrites it).
# ADDIN_URL = https://mail.example.com

The manifest is then served from https://<gateway>/addin/manifest.xml, with the gateway URL and a per-deployment identifier substituted for you.

Deployment is by sideloading. In the Microsoft 365 admin centre, go to Settings → Integrated apps → Upload custom apps, choose Provide link to manifest file, and give it that URL. There is no AppSource listing: the manifest’s content depends on your gateway’s URL, so there is no single artifact to publish. Besides, a store review that stands between you and a fix is a poor trade for one page of JavaScript.

Users without the add-in get the same effect from a subject keyword: [sign], [encrypt] or [secure] anywhere in the Subject. The encryption stage acts on it and removes it before the message is sent, so the recipient never sees it. The keywords are configurable (SUBJECT_KEYWORDS_SIGN, SUBJECT_KEYWORDS_ENCRYPT, SUBJECT_KEYWORDS_BOTH).

Note

A subject keyword means required, not try: a message that a user deliberately marked [encrypt] is not sent in the clear if a recipient has no key. ON_NO_KEY decides what happens instead. Unmarked mail under the default ENCRYPT = opportunistic still goes out in the clear without telling the sender, so a mistyped keyword is not caught (see Users send mail unencrypted by mistake because encryption state is unclear). The exception is a recipient whose key lookup failed in the DNS: the message is then not sent in the clear but deferred, sent to the portal or bounced, unless the sender writes [clear-ok] in the subject (or the operator sets CLEAR_ON_DNS_FAILURE); see A key lookup that fails in the DNS.

19.8. The X-Pepsi-* header contract

The contract consists of three fields in one namespace, plus the rule that makes the result field believable. (Ingress adds a fourth, X-Pepsi-Warning, to inbound mail that it has a reason to distrust, for example because of a From: display name naming a different address, a look-alike of a served domain, hidden characters, duplicated header fields or the like (Mail client extensions). For the same reason, it first removes any copy that a sender wrote.)

Field

Meaning

X-Pepsi-Sign

Request: sign this message. no/yes/required.

X-Pepsi-Encrypt

Request: encrypt this message. no/yes/required.

X-Pepsi-Crypto

Result: what the inbound stage found. Semicolon-separated key=value; rendered outside the message area by the add-in’s read pane and the Thunderbird extension (Mail client extensions).

Requests are honoured only for locally submitted mail (state.local_origin) and are stripped from outbound mail unconditionally, whatever STRIP_REQUEST_HEADERS says: a control channel that survived onto the wire would be a channel that the next hop could be told to obey.

The result header can be believed because the inbound stage removes the entire ``X-Pepsi-*`` namespace from every message it sees before adding its own. This includes a message that it is disabled for, one addressed to a domain that it does not serve, and one that it is about to split. The one field it keeps is ingress’s X-Pepsi-Warning on the outer header block, which ingress itself writes only after removing any copy a sender wrote; a copy inside decrypted content is removed like the rest. It follows that a message that did not traverse a decrypt stage carries no trustworthy result header, and nothing should present one as authoritative. We strip the namespace so that a sender cannot forge the verdict (see GnuPG status-line and output injection fools front ends). What a security indicator means states what each indicator promises a reader, and accepting the managed domains only from Pepsi above explains why the system behind the gateway must accept mail only from Pepsi.

Pepsi-Origin is deliberately not in this namespace and is never stripped, because the path that correlates payments with messages depends on it.

The result header’s signature value is one of none, valid, partial, valid-untrusted, invalid or unverifiable.

Danger

valid-untrusted means the signature verified against a key that is not anchored in any trust path, and anyone can produce such a signature. It must never be rendered as verified in a user interface, a task pane or a mail client rule (see Users skip, botch or cannot use key fingerprint verification).

19.9. Identity auto-provisioning

[pepsi-crypto] AUTO_CREATE_IDENTITY (on by default) lets Pepsi generate a key for a local sender who has none. The encrypt stage’s ENABLE_PEP decides when:

  • ENABLE_PEP = yes (the default, the pEp-style preset): on the sender’s first submitted message, whatever it asked for. Behind Exchange this covers everybody who sends through the connector, as long as Pepsi also receives mail for the sender’s domain: mail that the connector relays is locally submitted however the connector authenticates (SASL, MYNETWORKS or a client certificate), and the preset applies on every submission route to such a sender.

  • ENABLE_PEP = no: the first time that sender explicitly asks for protection – with the add-in, or with a subject keyword. It does not fire on ordinary mail.

Either way, an address that already has any key is never given another one automatically. This includes a key that the user registered from their mail client, and a revoked key.

This is how an organisation gets end-to-end coverage without per-user work: a key appears, and it is published so correspondents can use it.

It is also how an organisation publishes the address of every person who sends mail (or, without the preset, who ever asked for a signed message). An auto-created identity is marked published, and a published identity is served from this host’s own Web Key Directory. That is exactly what makes it usable, and also exactly what makes the address discoverable by anyone who guesses it. It is not uploaded to a public key server unless its owner asks (vks_wanted); [pepsi-keys] VKS_PUBLISH only decides the default for keys made by hand.

Both halves are wanted for a general-purpose deployment, but neither is obviously right for an organisation whose address list is itself sensitive, or one bound by a policy on disclosing staff addresses. The settings, from the most to the least automatic:

  • leave everything at its default: every sender gets a key on their first message, which can be discovered through this host’s WKD, so withdrawing it means unpublishing one identity rather than asking a key server to forget it;

  • set [stage-encrypt] ENABLE_PEP = no – keys appear only for senders who asked for protection;

  • turn AUTO_CREATE_IDENTITY off – key provisioning becomes an explicit act (an operator with pepsi-keys, or the user through the web console or the pepsi-keys@ control address), and a user who asks for encryption without a key gets whatever ON_NO_KEY says instead.

19.10. Key distribution

A correspondent can only encrypt to a key that they have, so the sender’s public key travels with their mail, in these ways:

  • Autocrypt (the default). Every locally submitted message carries an Autocrypt: header with the sender’s minimal OpenPGP key ([stage-encrypt] AUTOCRYPT, default yes). Thunderbird, K-9/FairEmail, Delta Chat and other Autocrypt-aware clients learn it silently. It rides on cleartext mail too, which is the point: until a correspondent has the key there is nothing to encrypt with.

  • An attached key file (optional). With ATTACH_KEYS_AS_FILES = yes the key is also attached as OpenPGP_0x<long key ID>.asc (application/pgp-keys), the classic OpenPGP way, for correspondents whose client does not read Autocrypt and imports keys from attachments. On encrypted mail the file is inside the ciphertext; on cleartext the message becomes multipart/mixed. The file is attached only until the correspondent has shown that they hold the key, by sending back a message encrypted to it and signed by them; pepsi-stage-autocrypt-learn records this on the inbound path. Regular correspondents therefore stop receiving the file, and a new key starts it again. Turn AUTOCRYPT off as well if you want the file only.

  • The Web Key Directory, served by pepsi-httpd for every published identity, for clients that look keys up rather than learn them from mail.

When a user has registered their own key from their mail client, that key is their public face: Pepsi then adds no Autocrypt: header and no key file (the client advertises its own), and the Web Key Directory serves only that key. See Key management.

19.11. Troubleshooting

Messages loop between Pepsi and Exchange.

The smarthost is pointed at your public MX rather than the tenant endpoint, or a served domain is routed to the direct-to-MX stage. Run pepsi-setup validate, which checks the configuration exactly as run does, without changing anything, and refuses both mistakes. If mail still loops, the running configuration is not the one that you validated. (pepsi-setup check is a different command: it compares the live DNS with the records that run would publish, and does not validate the pipeline.) Look for the loop with pepsi-queue: a message with a large number of Received: header fields gives it away.

Exchange Online rejects with 550 5.7.1 … S820.

The sending IPv6 address has no PTR. Publish one, or set ADDRESS_FAMILY = ipv4 on that MTA entry (Address family selection).

Exchange Online rejects with 550 5.7.64 TenantAttribution.

The inbound connector does not recognise the sender. Check that the connector lists the address Pepsi actually sends from — the IPv4 one if ADDRESS_FAMILY pins it.

Exchange Online’s outbound mail gets 550 5.7.1 Relaying denied.

With message not proven to come from a configured Exchange Online tenant, the journal of pepsi-ingress names the rule that failed. No DKIM signature … verified: DKIM signing for the domain is off in Microsoft 365, or the selector1/selector2 records are missing. Names tenant …: TENANT_ID is wrong. Two … fields: the message did not come from your tenant. Refused at RCPT already (recipient not in a served domain): the client address is outside SENDER_NETWORKS, or the envelope sender is not at one of the section’s DOMAINS.

Everything Exchange relays gets 550 5.7.1 Envelope sender not permitted.

RFC 6409 §6: the connector’s SASL account may only send as itself. Give it a USERNAME_MAP entry covering the served domains.

A delivery is using the wrong address family.

Precedence is the […-mta-*] entry, then the [stage-*] section, then any; the result is then intersected with what the host can route.

X-MS-* headers.

Exchange adds and consumes a number of X-MS-* headers. Pepsi does not read, rewrite or remove them; only the X-Pepsi-* namespace is touched. Be aware, though, that re-encoding a message for a next hop that lacks 8BITMIME rewrites the body and so invalidates any signature over it (see SMTP Protocol Extensions).

19.12. What Pepsi does not do

Journaling and archiving are out of scope. Exchange deployments frequently have a retention requirement, and Pepsi does not answer it: there is no archive store, no retention engine, no search and no legal-hold facility. See docs/ROADMAP.md.

Warning

[pepsi] MAIL_LOG is not an archive, and must not be presented to an auditor as one. It records no message content at any setting: at most the envelope, the outcome and, at full, the Subject: line. Its rows are pruned after [pepsi-admin] MAIL_LOG_RETENTION_DAYS, thirty days by default. It is an operational log with a retention limit, which is the opposite of a retention mechanism.

If you have a retention obligation, satisfy it with Exchange’s own journaling or a dedicated archiving product, and treat MAIL_LOG as telling you what happened last month, not what was said last year.

A crypto gateway is actually expected to answer a narrower question: was this message encrypted, and what did we decide about it? MAIL_LOG does answer that question, when it is enabled. Note that turning it on means the deployment keeps a record of who corresponds with whom; pepsi.conf(5) discusses that trade-off.