On this page0
Unfamiliar word? See Glossary: words used in these docs. Looking for the tasks in order? Begin at Start Here.
Reference
Outgoing Email (SMTP)
The mail settings, the provider presets, the test send, and what happens to each kind of email when no mail server is set up. The steps on screen are in Set up email.
Email leaves your instance over SMTP, to the one mail server you name. Most messages are sent at the moment something happens; compliance reminders are sent by a check that runs every 15 minutes. The settings are read again for each send, so a change takes effect on every part of Zonitix within 30 seconds, with no restart. Emails use your company name and logo from Branding.
When A Send Fails
- The mailer does not retry. A message the mail server refuses is written to the server log with the recipient and the error, and is not sent again. No delivery commitment is published.
- A sign-in link request still answers with the same message whether or not the email was sent, so the reply does not reveal which addresses have accounts. The link is valid for 15 minutes.
- A set-password invitation that cannot be emailed falls back to the one-time link, as it does with no mail server. The link is valid for 72 hours.
- A first sign-in invite that cannot be emailed leaves the account as it was, and that is written to the audit log.
Which workflow emails exist and who receives them is listed under What Gets Emailed, And To Whom. The sign-in link itself is described on SSO, Passwordless Login & SCIM.
What happens to each kind of email while no mail server is set up, the settings themselves and the audit actions are under Technical detail below.
If something here is not working as you expect, start with When something goes wrong.
The plain explanation is above. This part is for IT and developers: the exact settings, permission names, API addresses and data fields behind it. Closed: select the heading above to open it. While it is closed, your browser’s find-on-page (Ctrl+F or Cmd+F) does not search this part.
Endpoints
Session routes on your own instance’s API address, https://<your-instance>-api.zonitix.com. The mail settings are part of the security settings and are read and saved with them.
| Method | Path | Purpose | Auth |
|---|---|---|---|
| GET | /api/v1/auth/settings/security | Read the security settings, the mail settings among them. The mail server, port, username, From address, TLS switch and the two recipient lists are returned only to a caller who holds manage_security; every caller gets smtpConfigured. returns { smtpHost, smtpPort, smtpUser, smtpFrom, smtpSecure, smtpPassSet, smtpConfigured, itNotificationRecipients, hrNotificationRecipients, … } | manage_security, view_users or view_dashboard |
| POST | /api/v1/auth/settings/security | Save settings. Send only the fields you are changing. smtpPass is stored only when it is a non-empty string; an empty string keeps the saved one. body { smtpHost?, smtpPort?, smtpUser?, smtpPass?, smtpFrom?, smtpSecure?, itNotificationRecipients?, hrNotificationRecipients? } | manage_security, with a fresh step-up |
| POST | /api/v1/auth/settings/security/smtp/test | Send one test message. With host, user and pass all in the body it uses those without saving them; otherwise it uses the saved settings. body { to, host?, port?, user?, pass?, from?, secure? } returns { success: true, messageId, message } | manage_security |
| GET | /api/v1/auth/sso/status | Public. Tells the sign-in page whether a mail server is set up, so it can hide the sign-in link option. returns { enabled, protocol, preset?, smtpConfigured } | none |
The Settings
| Field | Meaning | When never set |
|---|---|---|
| smtpHost | The mail server’s address. | Empty |
| smtpPort | The port to connect on. | 587 |
| smtpUser | The username the mail server expects. | Empty |
| smtpPass | The sending credential. Write-only: encrypted with AES-256-GCM before it is stored, and never returned. The read shows only smtpPassSet, true or false. | Empty |
| smtpFrom | The address messages are sent from. | The username |
| smtpSecure | true opens the connection with TLS from the first byte (the usual setting for port 465). | true when the port is 465, otherwise false |
| itNotificationRecipients | Addresses for workflow emails that go to IT, separated by commas. | Empty |
| hrNotificationRecipients | Addresses for workflow emails that go to HR, separated by commas. | Empty |
- “Set up” means three things.
smtpConfiguredis true when a server, a username and a credential are all present. Nothing else is checked until a message is sent, so a wrong credential shows up at the test send, not at the save. - Encrypted connections. With
smtpSecureon, the connection is encrypted from the start. With it off on port 587 or 25, Zonitix requires the mail server to upgrade the connection (STARTTLS) and refuses to send the credential or the message if it does not. - Saving. Saving needs a fresh step-up; without one the reply carries
"error": "SUDO_REQUIRED". Fields you leave out are not changed.
Provider Presets
The Provider preset menu on Security Settings → Email / SMTP fills in the server, the port and the TLS switch, and renames the credential field to what that provider calls it. The SendGrid preset also sets the username to apikey. Custom / other fills in nothing: the fields keep what they held. A preset is a convenience of the screen: only the resulting server, port and switch are saved, and any SMTP server can be entered under Custom / other. Every provider preset leaves the TLS switch off, which on port 587 means the upgraded connection described above.
| Preset | Server | Port | Credential field |
|---|---|---|---|
| Custom / other | You type it | Not changed | Password / API key |
| Gmail / Google Workspace | smtp.gmail.com | 587 | App Password |
| Microsoft 365 / Outlook | smtp.office365.com | 587 | Account or App Password |
| SendGrid | smtp.sendgrid.net | 587 | API key |
| Mailgun | smtp.mailgun.org | 587 | SMTP password |
| Amazon SES | email-smtp.us-east-1.amazonaws.com (change the region to yours) | 587 | SMTP password |
Test Send
The test sends one real message, with the subject “<your company name> email test” and the heading “Your email is working”, to the address in to. It is the direct way to find out whether the mail server accepts your settings: saving them does not contact the mail server.
// Test the saved settings.
POST /api/v1/auth/settings/security/smtp/test
{ "to": "you@your-company.example" }
// 200
{ "success": true, "messageId": "…", "message": "Test email sent to you@your-company.example." }
// 424 — the mail server's own error text
{ "success": false, "error": "…" }
| Status | Meaning |
|---|---|
| 200 | The mail server accepted the message. The reply carries success: true and the server’s message id. Accepted is not the same as delivered: check the inbox. |
| 400 | No to address; or no usable settings (“SMTP is not configured. Enter host, username and password (or save them) first.”). |
| 424 | The mail server refused the connection, the sign-in or the message. The reply carries success: false and the mail server’s own error text. |
| 403 | The caller does not hold manage_security. |
When No Mail Server Is Set Up
Each kind of email has its own behaviour. Where a person would otherwise wait for a message that cannot arrive, Zonitix refuses or hands the administrator a link instead of reporting a send that did not happen.
| With no mail server | |
|---|---|
| Set-password invitation (a new user, a resend, the support account) | Not emailed. The one-time link is returned to the administrator who issued it, to pass on by hand, and that is audited as USER_INVITE_LINK_ISSUED. If the account holds access that administrator could not grant themselves, the link is withheld and the refusal is audited as USER_INVITE_LINK_REFUSED. |
| Sign-in link (magic link) | The request answers 409 and no link is made. The sign-in page hides the option. |
| First sign-in invite from Users (POST /api/v1/auth/security/users/:userId/invite) | Answers 409. The account is not activated, so it can be invited once email works. |
| Workflow step that creates a Zonitix account | The account is created but no invite is sent, and the step’s result says so. |
| “It is your turn” email for a workflow step | Not sent. The step still waits in its queue in the app. |
| Provisioning issue alert | Not emailed. The in-app alert is still created. |
| Temporary password for a new directory account | Not emailed. The password is shown on the workflow step instead. |
| Phishing simulation | Sending does not start; the reason given is that outgoing email is not set up. |
| Compliance reminders, such as vendor review reminders | Not sent. |
| Notices that support access was granted, revoked or expired | Not sent. The audit entries are still written. |
| Any other email | Skipped. The server log records the recipient and subject of the skipped message; it is not kept to be sent later. |
What Is Audited
| Action | Written when |
|---|---|
| SECURITY_POLICY_CHANGED | Settings were saved. The entry reads “SMTP / email settings updated” when a mail setting changed, and names a recipient list with its new value when that changed. The credential is not written to the log. |
| SMTP_TEST_SENT | A test message was accepted, with the mail server and the recipient. |
| SMTP_TEST_FAILED | A test message failed, with the mail server, the recipient and the error. |
| SUDO_REQUIRED | A save was attempted without a fresh step-up. |
| MAGIC_LINK_REQUESTED | A sign-in link was requested for an existing account. The link itself is not written to the log. |
| USER_INVITED, USER_INVITE_RESENT | An invitation was issued. On a set-password invitation, delivery is email or manual_link. USER_INVITED is also written when a first sign-in invite is sent. |
| USER_INVITE_LINK_ISSUED | A one-time link was shown to an administrator for manual delivery. |
| USER_INVITE_LINK_REFUSED | A one-time link was withheld from the administrator who asked for it. |
| USER_INVITE_EMAIL_FAILED | A first sign-in invite could not be emailed, and the account was left as it was. |