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:

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.

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.

API

Get current config

GET /api/v1/settings/smtp
Authorization: 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/smtp
Authorization: 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/test
Authorization: Bearer <admin-token>
Content-Type: application/json

{ "to": "you@example.com" }

Remove database config

DELETE /api/v1/settings/smtp
Authorization: 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

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

Related

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