Skip to content

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.

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: Edit is 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.

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.

  1. Mint an account-owned token with the Email Sending: Edit permission. If the sender’s Vault secret is Terraform-managed, copy the pattern in tf/cloudflare/nas_email.tf: a cloudflare_account_token plus a vault_kv_secret_v2, with the permission-group id resolved by name, so that a renamed group fails the plan. The bootstrap token must itself hold Email Sending: Edit before 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.
  2. Store the token as cf_email_token on the sender’s own Vault secret, with an email_from field on an @hl.fzymgc.house address. Do not create a separate path for the token. Add the keys to the secrets reference.
  3. Point the sender at the transport: implicit TLS on 465, username api_token, password from cf_email_token, sender from email_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.
  4. Make sure that the sender’s Vault policy grants read on its secret. A Terraform consumer needs the grant in its tf/vault policy. An ExternalSecret consumer needs nothing, because the external-secrets-operator policy reads every path under cluster/.

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
  1. Trigger a send. For Keycloak, use Forgot password, or Test connection under Realm settings, Email, in the admin console.
  2. Make sure that the message appears in the Email Sending activity log in the Cloudflare dashboard, attributed to the sender’s token.
  3. Read the sender’s own logs and default.otel_logs in ClickStack for send errors. The common causes are a username other than api_token, STARTTLS on 587 instead of implicit TLS on 465, and a MAIL FROM domain that is not onboarded.