Email

Qualor sends email through an SMTP server you choose: a test message, alerts for administrators, account emails (password reset links, invitations, the password-changed notice), and project notifications for the projects you watch. Nothing is sent until an instance administrator or the operator sets up a server. Qualor never tracks whether a message was opened or a link clicked.

What Qualor sends

Each alert has a switch in Settings → Email → Alerts for administrators; both are on. Organisation administrators turn their failing-webhook email off in Settings → Notifications (below). An administrator without an email address gets nothing: add one in Settings → Users. The panel says how many administrators have none.

Every message has an HTML part and a plain-text part. Its links lead to the address in QUALOR_PUBLIC_URL; without it, a message says where to go in Qualor instead, and Settings → Email warns.

Account emails

With an SMTP server, Qualor also sends these to people with an email address on their account. The reset and invitation emails also need QUALOR_PUBLIC_URL, because they carry a link; the password-changed notice needs only the SMTP server (without QUALOR_PUBLIC_URL it just has no link to reset the password).

• Reset your Qualor password, after someone uses Forgot password? on the sign-in page. The link works once, for 60 minutes. It does not sign anyone in: the person signs in with the new password afterwards.
• The inviter’s name, then “invited you to Qualor”, when an instance admin invites a new user from Settings → Users. The link works once, for 7 days, and the admin can resend or revoke it.
• Your Qualor password was changed, after a reset through a link, a change of one’s own password, or a reset by an administrator. It names the account, the time (UTC) and, for a change the person made, the address it came from.

The secret part of each link comes after # in the address, so it never reaches the server’s logs, a proxy or another site. Qualor stores only a hash of it, and deletes a message’s body from the database once the message is delivered.

Without an SMTP server or without QUALOR_PUBLIC_URL, the sign-in page shows no Forgot password?, Settings → Users creates users with an initial password only, and an instance admin resets forgotten passwords. See Users, projects and tokens.

Project notifications

Anyone who can see a project can watch it and get an email when something needs them:

Watching a project

On a project’s page, press Watch (the bell). Watching starts with the main branch and all three emails. Press Watching to change it:

• Main branch, or All branches and merge requests;
• each of the three emails on or off: The quality gate fails, The quality gate passes again and An analysis fails;
• Stop watching.

Settings → Notifications lists every project you watch, with the same choices, and has the switch for all notification email, Email me at your address.

Nobody watches anything until they press Watch: creating a project watches nothing.

Who gets the email

An email goes to you only while all of these hold:

• you can still see the project: a role in its organisation, a role on the project, or instance administrator. If you lose access, the emails stop; they start again if you get access back;
• your account is active and has an email address. An instance administrator sets it in Settings → Users;
• Email me at … is on in Settings → Notifications;
• email is set up on the server (see the top of this page).

The read-only demo account never gets email.

Stopping the emails

Every email ends with Stop watching this project and Notification settings. Stop watching works without signing in. Opening the link in a browser shows a page that asks once, then stops, so a mail scanner that opens links stops nothing. Mail apps with a one-click unsubscribe button (Gmail, Apple Mail, Outlook) stop watching in one click, without the question. Without QUALOR_PUBLIC_URL the emails have no links; use Settings → Notifications instead.

Failing webhooks for organisation administrators

Organisation administrators also get the failing-webhook email for their organisation’s webhooks, Slack and Teams ones too (see Webhooks), at most once a day per webhook. Turn it off in Settings → Notifications with Failing webhooks in organisations I administer; turning off Email me at … stops it too. An instance administrator who is also an organisation administrator gets it once, not twice.

Set up in Qualor

An instance administrator opens Settings → Email:

1. Under SMTP server, enter the Host, the Security and the Port, the Username and Password if the server needs them, the From name and From address, and optionally a Reply-to address. Press Save. The password is stored encrypted with QUALOR_SECRET_KEY and never shown again: Replace enters a new one, Remove deletes it. An empty Host turns email off when you save.
2. Under Send a test message, check the address (yours by default) and press Send test. The page shows the server’s answer, or why it refused.

Set up with environment variables

The operator can set the server instead. Then Settings → Email shows it read-only, marked Set by the environment; the alert switches can still be changed there.

URL-encode special characters in the user name and the password: @ as %40, : as %3A, / as %2F, % as %25. A mistake in these variables stops the server at start, and the message names the variable, never the password.

Examples:

• Microsoft 365: smtp://qualor%40example.com:<password>@smtp.office365.com:587. The mailbox needs SMTP AUTH turned on (Microsoft 365 admin center → the user → Mail → Manage email apps → Authenticated SMTP).
• Gmail or Google Workspace: smtp://qualor%40example.com:<app password>@smtp.gmail.com:587, with an app password of that account (it needs 2-step verification), not its normal password.
• Amazon SES: smtps://<SMTP user name>:<SMTP password>@email-smtp.eu-west-1.amazonaws.com:465, with SES’s SMTP credentials (not an access key). The From address must be a verified identity.
• A relay on your network: smtp://postfix.internal:25?security=none.

With Docker Compose, add to .env:

QUALOR_SMTP_URL=smtp://qualor%40example.com:<password>@smtp.office365.com:587
QUALOR_SMTP_FROM=Qualor <qualor@example.com>

and uncomment the two QUALOR_SMTP_… lines of compose.yml (Install the server). With Helm, see Settings.

TLS and private certificate authorities

Qualor always checks the SMTP server’s certificate, and speaks TLS 1.2 or later. There is no setting to accept a certificate that does not verify. When your mail server’s certificate comes from a private certificate authority, give the server that CA in NODE_EXTRA_CA_CERTS (Server settings).

Delivery, retries and the log

A message is stored in the same database transaction as what it is about, so it is never sent for something that did not happen. Qualor then sends it on its own: a slow mail server never delays analyses.

• A temporary failure (the server cannot be reached, does not answer in time, or answers with a 4xx code such as greylisting) is retried 1, 2, 4, 8, 16 and 32 minutes later: 7 attempts over about an hour. When the last one fails too, the message is Failed and stays in the log; it is not sent later.
• A permanent failure (a 5xx answer, a refused password, a certificate that does not verify, or STARTTLS not offered) fails the message at once.
• A message still waiting after 2 days is given up and failed.

Recent messages in Settings → Email lists every message with when it was queued, the recipient, the subject and its status (Delivered, Retrying n/7, Failed or Pending), with the server’s answer or the error. The body of a message is kept encrypted only while it waits, and deleted once it was sent or failed; the log keeps the subject, the recipient, the status and the server’s answer for 30 days (Retention).

The API is GET /api/v0/system/mail and PUT /api/v0/system/mail (the settings; the password is write-only), POST /api/v0/system/mail/test ({ "to": "you@example.com" }) and GET /api/v0/system/mail/messages (REST API); instance administrators only. Changing the settings and sending a test are in the audit log.

Troubleshooting