Outbound Email (Cloudflare Email Sending)
Applications in the cluster send transactional email through Cloudflare Email Sending over authenticated SMTP submission. Each sender holds its own Cloudflare API token. This page states the transport, where each credential lives, and the procedure to onboard a new sender.
The transport
Section titled “The transport”| Property | Value |
|---|---|
| Host | smtp.mx.cloudflare.net |
| Port | 465 |
| Security | implicit TLS (SMTPS), not STARTTLS |
| SMTP username | the literal string api_token, the same for every sender |
| SMTP password | a Cloudflare API token with the Email Sending: Edit permission |
| Sender domain | hl.fzymgc.house |
Two facts shape every integration:
- The per-sender credential is the password. The username is always
api_token. Email Sending: Editis account-scoped. A token can send from any onboarded domain on the account. A token per sender buys independent rotation and per-token attribution in the Email Sending activity log, not domain isolation. Treat every token as a full send credential.
The envelope sender (MAIL FROM) must be on an onboarded domain, or Cloudflare rejects the
message. The sending domain and its MX, SPF, DKIM and DMARC records live in the Cloudflare
dashboard under Email Service, not in this repository. Read the onboarding status there.
Senders
Section titled “Senders”| Sender | Token minted by | Vault path under secret/fzymgc-house/ |
Transport configuration |
|---|---|---|---|
| Keycloak | the operator, in the Cloudflare dashboard | cluster/keycloak (cf_email_token, email_from) |
the smtp_server block in tf/keycloak/main.tf |
| NAS alerts | tf/cloudflare/nas_email.tf |
infrastructure/nas/cloudflare-email |
the nas-mail role, through the TrueNAS middleware with security: SSL |
| Turing Pi nodes | tf/cloudflare/nodes_email.tf |
infrastructure/nodes/cloudflare-email |
the postfix satellite that tp2-bootstrap-node renders |
Keycloak’s token is operator-seeded, because its cluster/keycloak secret is operator-seeded and
a vault_kv_secret_v2 write would replace it. The tf/vault grant for a Terraform-minted path
must apply before the main-cluster-cloudflare workspace writes it.
The node relay differs from the application senders in two ways. Node mail originates as
root@<node>.fzymgc.house, so postfix rewrites the envelope sender to nodes@hl.fzymgc.house
through smtp_generic_maps. The tp2-bootstrap-node role reads the token over the operator’s
Vault session at play time, so the nodes hold no Vault credential. If Vault was unreachable during
a converge, run the mail tag again.
Onboard a new sender
Section titled “Onboard a new sender”- Mint an account-owned token with the
Email Sending: Editpermission. If the sender’s Vault secret is Terraform-managed, copy the pattern intf/cloudflare/nas_email.tf: acloudflare_account_tokenplus avault_kv_secret_v2, with the permission-group id resolved by name, so that a renamed group fails the plan. The bootstrap token must itself holdEmail Sending: Editbefore it can mint a token with that group (tf/cloudflare/CLAUDE.md). If the sender’s secret is operator-seeded, mint the token in the Cloudflare dashboard and write it to Vault by hand. - Store the token as
cf_email_tokenon the sender’s own Vault secret, with anemail_fromfield on an@hl.fzymgc.houseaddress. Do not create a separate path for the token. Add the keys to the secrets reference. - Point the sender at the transport: implicit TLS on 465, username
api_token, password fromcf_email_token, sender fromemail_from. Host, port and username are not secret, so write them in the sender’s configuration and read only the token and the sender from Vault. - Make sure that the sender’s Vault policy grants read on its secret. A Terraform consumer needs
the grant in its
tf/vaultpolicy. An ExternalSecret consumer needs nothing, because theexternal-secrets-operatorpolicy reads every path undercluster/.
Every framework defaults to STARTTLS and needs its implicit-TLS setting:
| Framework | Setting |
|---|---|
Keycloak (keycloak_realm.smtp_server) |
ssl = true, port = "465" |
| Django | EMAIL_USE_SSL set to "1" and port 465, not EMAIL_USE_TLS |
TrueNAS (midclt mail.update) |
security: "SSL", port 465 |
| Postfix | smtp_tls_security_level=encrypt, smtp_tls_wrappermode=yes, relayhost=[smtp.mx.cloudflare.net]:465 |
Check a sender
Section titled “Check a sender”- Trigger a send. For Keycloak, use Forgot password, or Test connection under Realm settings, Email, in the admin console.
- Make sure that the message appears in the Email Sending activity log in the Cloudflare dashboard, attributed to the sender’s token.
- Read the sender’s own logs and
default.otel_logsin ClickStack for send errors. The common causes are a username other thanapi_token, STARTTLS on 587 instead of implicit TLS on 465, and aMAIL FROMdomain that is not onboarded.