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, the test emails sent from the app, emails AgentQ sends when asked to notify someone, and the account emails that carry user invitations and password reset links. Without SMTP configured, none of those are delivered unless an Email integration provides delivery.

Qualytics never emails reports or files. Scheduled Export operations write their results as tables in the linked enrichment datastore, and the Export button on the Insights page downloads a PDF in your browser.

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: both must be set for either to take effect, so filling in only one results in neither being used. Leave both empty and Qualytics connects without authentication, which is suitable only for trusted internal relays.

These settings are read when the application services start, so changes take effect only after a restart. An Email integration saved in the app overrides them for every email, as described in Overriding the deployment email service.

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. The install template you start from sets it to `false`, so a new deployment has no email service until you turn it on.
`controlplane.smtp.server`	SMTP host as a bare hostname, without `http://` or `https://`. 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. Only `465` (implicit TLS), `587` (STARTTLS), and `25` (unencrypted internal relays) are accepted. Leave the field out and the chart's own default of `465` applies, but never set it to an empty string. An empty or unsupported value is not caught at install time and fails when an email is actually sent.
`controlplane.smtp.sender`	The `From` address shown on outgoing emails, displayed to recipients as `Qualytics Platform <sender>`. Must be a sender your SMTP provider has authorized, and should be a real monitored address. Always set it: an enabled service with an empty sender still counts as configured, so the app has no address to show and every message goes out with an empty `From`, which most providers reject.
`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

AWS SESGmail / Google WorkspaceMicrosoft 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: "<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.

A narrower alternative exists when only your email relay uses a private certificate: connect an Email integration with Verify TLS Certificates cleared. That setting affects only that email server, and leaves certificate validation in place everywhere else. Neither setting has any effect on port 25, which uses no TLS at all.

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. The settings are read when a service starts, so they are not picked up until both services are rolled:

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

Sign in as a user with the Manager or Admin role, since the Integrations tab is not visible to other roles, and open Settings > Integrations. When the deployment email service is configured, the Email row under Alerting shows a Connected indicator, has no Connect button, and its options menu offers Configure.

Open Configure to confirm the sender address. With Use a custom SMTP server switched off, the note in the dialog states that email is sent through the email service configured for this deployment and names the address it sends from. That note is the only place in the interface that shows this sender address. If the note names no address, controlplane.smtp.sender is unset.

The app exposes nothing else about this service: the server, port, username, and password are never shown and cannot be edited there. The integration's Validate button only tests values typed into that form, so it is not a way to test the deployment email service. To verify actual delivery, run a controlled Flow with an Email notification to a test address, or use that action's Test Notification button, and confirm that the message arrives.

If the Email row still shows a Connect button, reload the page first, because the row falls back to that presentation when it cannot read the deployment email status. If it persists, confirm that controlplane.smtp.enabled is true, reapply the complete values file, and restart the application services.

Overriding the deployment email service

While controlplane.smtp.enabled is true, an Email integration saved in the app overrides these settings for every email the platform sends, including user invitations and password reset links. The Email row then carries a Custom badge.

Because removing that override never turns email off, Qualytics offers no Disconnect action on the Email row in this state. The override is removed from inside the dialog: open Configure, switch Use a custom SMTP server off, and click Update. That discards the override's stored settings and delivery returns to the deployment email service.

With controlplane.smtp.enabled set to false, the Email row behaves like any other integration: it shows a Connect button, there is no custom-server switch, Disconnect is available, and using it leaves the deployment with no email delivery at all.

Running without an email service

When neither an Email integration nor a deployment email service exists, nothing is queued and nothing is retried. What a user sees depends on which email was being sent:

Email	What happens
Flow Email notification action	The run is marked failed and the reason, naming a missing email server, appears in the run's Logs section.
Test Notification on a Flow Email action	The failure is reported immediately in the Flow editor.
AgentQ email	The send fails and AgentQ reports the failure in the conversation.
User invitation	The invitation is still created. The dialog warns that the email could not be sent and offers the invitation link to share manually. The link is shown only at that moment, so an Admin who dismisses the dialog has to send a new invitation to get another link.
Password reset link	Nothing is delivered, and the page still shows its usual confirmation, so the user gets no indication of the failure. No one can set the password on their behalf, so email delivery has to be working before they request the reset again.

Troubleshooting

Symptom	Likely cause	Fix
A failure naming a missing email server	Neither a deployment email service nor an Email integration is configured	Confirm `controlplane.smtp.enabled` is `true` and reapply the complete values file, or connect an Email integration.
Delivery still fails after SMTP was enabled or the settings were corrected	The application services were not restarted, so the previous settings are still in use	Restart the application services as described in Apply and verify, then test delivery again.
A failure stating that the configured credentials are invalid	Wrong username or password, or the provider requires an app-specific password or a provider-issued SMTP credential	Regenerate the credentials with your provider and update `secrets.smtp`.
A failure stating that the addresses were refused by the server	`sender` is not a verified address on the provider account, or the provider will not deliver to those recipients	Verify the sender address with your provider; for SES, check the sandbox status, which restricts which recipients you can email.
A failure about the server's certificate	Relay uses a private CA that Qualytics does not trust	Import the CA into the application image, set `controlplane.egress.verifyTLSCertificates: false`, or connect an Email integration with Verify TLS Certificates cleared.
A failure stating that the server could not be reached, or the attempt times out	A network policy or egress firewall blocks outbound SMTP	Allow egress from the Qualytics namespace to the SMTP host on the configured port.
Delivery fails only on port `587`	The relay does not offer STARTTLS on port `587`, or that port expects implicit TLS instead	Confirm the port matches the provider's transport: `465` for implicit TLS, `587` for STARTTLS.