SMTP Settings

Nexus GSLB can send email for two purposes:

Password reset — delivers a one-time token when a user clicks "Forgot password?"
Health alerts — notifies operators when a member transitions between healthy and unhealthy

SMTP can be configured in two ways:

Method	Precedence	Editable at runtime
Database (WebUI / API)	Higher	Yes — applies immediately
`gslbd.yaml` `alerts.smtp`	Lower	No — requires restart

If a database configuration exists, it takes precedence over the YAML file. Deleting the database configuration restores the YAML config on the next restart.

WebUI — Admin → Settings

Navigate to Admin → Settings and expand the SMTP / Email section.

Field	Description
SMTP Host	Hostname of your outbound mail server
Port	`587` for STARTTLS, `465` for implicit TLS
From address	Envelope sender (e.g. `nexus@example.com`)
Alert recipients	Comma-separated list of addresses for health alert emails
Username	SMTP auth username (leave blank for unauthenticated relays)
Password	SMTP auth password — leave blank to keep the existing stored value
Implicit TLS	Enable for port-465 "SMTPS" connections
STARTTLS	Enable for opportunistic TLS upgrade on port 587
Enabled	Toggle to temporarily disable outbound email without removing the config

Test button

Enter any email address in the "Send test to…" field and click Test. A test message is delivered immediately using the saved config. The result (success or error detail) is shown inline.

Source badge

The badge next to the section heading shows Database when the DB config is active, or Not configured when neither DB nor YAML provides an SMTP config.

APIGet current config

GET /api/v1/settings/smtpAuthorization: Bearer <admin-token>

{  "host": "smtp.example.com",  "port": 587,  "from": "nexus@example.com",  "to": ["ops@example.com"],  "username": "nexus@example.com",  "hasPassword": true,  "tls": false,  "startTls": true,  "enabled": true,  "source": "database"}

password is never returned. hasPassword indicates whether one is stored.

Save / update config

PUT /api/v1/settings/smtpAuthorization: Bearer <admin-token>Content-Type: application/json{  "host": "smtp.example.com",  "port": 587,  "from": "nexus@example.com",  "to": ["ops@example.com", "noc@example.com"],  "username": "nexus@example.com",  "password": "secret",  "tls": false,  "startTls": true,  "enabled": true}

Omit or send an empty "password" to keep the currently stored password unchanged.

Changes take effect immediately — no restart required.

Send a test email

POST /api/v1/settings/smtp/testAuthorization: Bearer <admin-token>Content-Type: application/json{ "to": "you@example.com" }

Remove database config

DELETE /api/v1/settings/smtpAuthorization: Bearer <admin-token>

Clears the live mailer and alerter email config. The YAML config takes effect on the next restart.

YAML config (alternative)

If you prefer to manage SMTP purely through config files, set it in gslbd.yaml:

alerts:  smtp:    - host: smtp.example.com      port: 587      from: "nexus@example.com"      to:        - ops@example.com      username: "nexus@example.com"      password: "secret"      startTls: true

The YAML config is static — changes require a daemon restart. Database config always overrides YAML when both are present.

Permissions

Permission	Grants
`settings:read`	View current SMTP config (password masked)
`settings:write`	Create, update, delete, and test SMTP config

Only tenant_admin has these permissions by default. Operators and viewers cannot view or modify server settings.

Password Reset — uses SMTP to deliver one-time reset tokens
Alerting — uses SMTP for health transition notifications