SMTP Configuration

Self-hosted deployments only

This guide is for self-hosted deployments. Qualytics operates email delivery for managed deployments.

This guide explains how to configure outbound email delivery for a self-hosted Qualytics deployment. Qualytics uses SMTP to send user invitations, password resets, scheduled report deliveries, and operational notifications. Without SMTP configured, those email-driven flows are disabled but the rest of the platform continues to function.

How it works

Two Helm value groups configure SMTP:

Group	Purpose	Where it lives in `values.yaml`
`controlplane.smtp`	Connection settings (server, port, sender, enable toggle)	Application settings
`secrets.smtp`	Optional credentials for relays that require authentication	Secrets settings

When controlplane.smtp.enabled is true, Qualytics connects to the configured SMTP service. Provide both credential fields when the service requires authentication. If either credential is empty, Qualytics connects without authentication, which is suitable only for trusted internal relays.

Required configuration

Add the following to your values.yaml (or your chart overrides):

controlplane:
  smtp:
    enabled: true
    server: "smtp.example.com"
    port: "465"
    sender: "no-reply@your-company.com"

secrets:
  smtp:
    smtp_sender_user: "your-smtp-username"
    smtp_sender_password: "your-smtp-password"

Field	Description
`controlplane.smtp.enabled`	Master toggle. Set to `false` to disable SMTP entirely.
`controlplane.smtp.server`	SMTP host. Examples: `email-smtp.us-east-1.amazonaws.com` (AWS SES), `smtp.gmail.com`, `smtp.office365.com`, or your internal relay.
`controlplane.smtp.port`	SMTP port as a string. Use `465` for implicit TLS (SMTPS), `587` for STARTTLS, or `25` for unencrypted internal relays.
`controlplane.smtp.sender`	The `From` address shown on outgoing emails. Must be a sender your SMTP provider has authorized.
`secrets.smtp.smtp_sender_user`	SMTP username. Leave empty for anonymous (no-auth) relays.
`secrets.smtp.smtp_sender_password`	SMTP password or provider-specific access token. Leave empty for anonymous relays.

Sender address must be authorized

Most SMTP providers (AWS SES, Gmail, Office 365) reject mail when the From address is not a verified or authorized sender on the account. Verify your sender value with your provider before deploying.

Common providers

AWS SESGmail / Google WorkspaceOffice 365 / Exchange OnlineInternal relay (anonymous)

controlplane:
  smtp:
    enabled: true
    server: "email-smtp.us-east-1.amazonaws.com"
    port: "465"
    sender: "no-reply@your-verified-domain.com"

secrets:
  smtp:
    smtp_sender_user: "<SES_SMTP_USERNAME>"
    smtp_sender_password: "<SES_SMTP_PASSWORD>"

SES SMTP credentials are not the same as your AWS access keys. Generate them from the SES console under SMTP settings > Create SMTP credentials. The sender domain or address must be verified in SES, and your account must be moved out of the SES sandbox to email arbitrary recipients.

controlplane:
  smtp:
    enabled: true
    server: "smtp.gmail.com"
    port: "465"
    sender: "no-reply@your-workspace-domain.com"

secrets:
  smtp:
    smtp_sender_user: "no-reply@your-workspace-domain.com"
    smtp_sender_password: "<APP_PASSWORD>"

Use a Google App Password. Regular account passwords will not work. The account must have 2-Step Verification enabled.

controlplane:
  smtp:
    enabled: true
    server: "smtp.office365.com"
    port: "587"
    sender: "no-reply@your-tenant.onmicrosoft.com"

secrets:
  smtp:
    smtp_sender_user: "no-reply@your-tenant.onmicrosoft.com"
    smtp_sender_password: "<APP_PASSWORD>"

Office 365 requires STARTTLS on port 587. SMTP AUTH must be enabled on the mailbox. Microsoft disables it by default for tenants created after 2020, so your administrator may need to enable it through PowerShell.

controlplane:
  smtp:
    enabled: true
    server: "internal-relay.your-company.local"
    port: "25"
    sender: "no-reply@your-company.com"

secrets:
  smtp:
    smtp_sender_user: ""
    smtp_sender_password: ""

Leave both credential fields empty only when the internal relay authorizes Qualytics by source IP or network position and does not require SMTP authentication.

TLS certificate validation

Qualytics validates TLS certificates on outbound SMTP sessions by default. If your relay uses a private CA or self-signed certificate, disable validation globally:

controlplane:
  egress:
    verifyTLSCertificates: false

This setting also disables validation for HTTP egress and other outbound TLS sessions, so prefer importing your private CA into the application image when possible.

Apply and verify

Apply the changes with the complete protected values.yaml for this installation. The file must retain the unique secrets.deployment.identifier provided by Qualytics. Do not pass the deployment identifier through --set.

CHART_VERSION="<version provided by Qualytics>"

helm upgrade qualytics qualytics/qualytics \
    --namespace qualytics \
    --version "$CHART_VERSION" \
    -f values.yaml \
    --wait \
    --timeout=20m

Restart the application services to load the new settings:

kubectl rollout restart deployment -n qualytics qualytics-api qualytics-cmd
kubectl rollout status deployment/qualytics-api -n qualytics
kubectl rollout status deployment/qualytics-cmd -n qualytics

Confirm that the API workload received the SMTP connection settings without displaying their values:

kubectl exec -n qualytics deployment/qualytics-api -- sh -c \
  'test -n "$SMTP_SERVER" && test -n "$SMTP_PORT" && test -n "$SMTP_SENDER_EMAIL" && echo "SMTP connection settings are present"'

This check intentionally does not print SMTP credentials. If it does not report success, confirm that controlplane.smtp.enabled is true and reapply the complete values file.

To verify delivery, invite a test user from Settings > Users and confirm the invitation email arrives.

Troubleshooting

Symptom	Likely cause	Fix
No emails sent, no errors in logs	`controlplane.smtp.enabled` is `false`, or the deployment was not restarted after the settings changed	Confirm `enabled: true`, restart the application services, and test delivery again.
`SMTPAuthenticationError`	Wrong username/password, or the provider requires an app-specific password / SES SMTP credential	Regenerate credentials with the provider and update `secrets.smtp`.
`SMTPSenderRefused`	`sender` is not a verified address on the provider account	Verify the sender address with your provider; for SES, check the SES sandbox status.
`SSLError` / `CertificateVerifyFailed`	Relay uses a private CA that Qualytics does not trust	Either import the CA into the application image or set `controlplane.egress.verifyTLSCertificates: false`.
Connection timeout	NetworkPolicy or egress firewall blocks outbound SMTP	Allow egress from the Qualytics namespace to the SMTP host on the configured port.
`Connection unexpectedly closed` on port 587	Relay requires STARTTLS but is being approached as implicit TLS	Confirm the port matches the provider's authentication mode (`465` for SMTPS or `587` for STARTTLS).