Skip to content

SMTP Configuration

  • Self-hosted

This guide explains how to configure the default outbound email service for a self-hosted Qualytics deployment. Qualytics uses SMTP for Flow email notifications and scheduled report deliveries. Without SMTP configured, those email-driven features are unavailable unless an Email integration provides delivery.

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 Password or provider-issued SMTP credential. 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

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: "<SMTP_AUTH_CREDENTIAL>"

Exchange Online requires STARTTLS on port 587, and SMTP AUTH must be enabled for the mailbox. Qualytics currently supports SMTP username and password authentication, but not OAuth for SMTP.

Microsoft states that Basic SMTP AUTH behavior remains unchanged through December 2026. At the end of December 2026, it will be disabled by default for existing tenants and unavailable by default for new tenants. Microsoft identifies OAuth as the supported authentication method for new tenants, but Qualytics does not currently support OAuth for SMTP. If your policy does not allow Basic SMTP AUTH, use an approved internal relay or another SMTP provider. Review Microsoft's current deprecation timeline before choosing this option.

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

Open Settings > Integrations and check the Email card. With the default service available and no Email integration connected, the card indicates that email notifications use the platform default.

To verify delivery, run a controlled Flow with an Email notification to a test address and confirm that the message arrives. If the Email card does not show a default service, confirm that controlplane.smtp.enabled is true, reapply the complete values file, and restart the application services.

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).