Email Configuration (SMTP)

Super Admins can maintain more than one SMTP sender, mark one as the platform default, and optionally override that default per team. Platform email (including on-premises password reset) uses the resolved configuration for the team context when one applies.

This is separate from the SMTP toolkit on agents/workflows (those credentials live on the toolkit). Email Configuration is the platform mail path for system messages such as invites, notifications, and password reset.

Prerequisites

• You are a Super Admin (Email Configuration is Super Admin–only; see RBAC).
• Your mail provider allows SMTP from the EKB host (firewall / IP allowlists as needed).
• You know the provider’s host, port, and whether it expects TLS (STARTTLS) or SSL (implicit TLS).
• For on-premises password reset and system mail, at least one healthy configuration should be marked Default.

Where to find it

Open Super Admin → Email Configuration. Two sub-tabs:

Tab	Purpose
SMTP Settings	Create, edit, test, deactivate, and set the default SMTP config
Templates	Edit the HTML/subject of platform email templates

The SMTP Settings layout is a list of configurations on the left and a detail form on the right. Badges show Default and Active when applicable. Use New SMTP to start a blank form.

Field reference

Required to save: Name, Host, and Sender email.

Field	Required	Description
Name	Yes	Display label in the list and in the team SMTP picker (for example Transactional Email or EU relay).
Host	Yes	SMTP server hostname (for example smtp.example.com).
Port	No (defaults to 587)	Common values: 587 with TLS, 465 with SSL, sometimes 25 or 2525 for relays.
Username	No	Login user for authenticated SMTP. Leave blank for unauthenticated relays.
Password	No	SMTP password or app password. Leave blank when editing to keep the stored password.
Clear saved password	—	Appears on existing configs when no new password is typed. Clears the stored secret on the next save. Use Undo clear to cancel.
Sender email	Yes	From address used for platform mail.
Sender name	No (defaults to System)	Display name shown next to the From address.
TLS	—	STARTTLS after connect. Typical with port 587. Do not enable TLS and SSL together unless your provider requires a specific combination.
SSL	—	Implicit SSL/TLS from the first connection. Typical with port 465.

Passwords are stored encrypted when platform email encryption is configured.

Common provider patterns

Provider pattern	Host (example)	Port	Security
Gmail / Google Workspace (app password)	smtp.gmail.com	587	TLS on
Microsoft 365 / Outlook	smtp.office365.com or smtp-mail.outlook.com	587	TLS on
Corporate relay (internal)	Your relay hostname	25 / 587	Often TLS; auth may be optional

Always follow your provider’s current documentation for host, port, and authentication.

Add or edit a configuration

1. Go to Super Admin → Email Configuration → SMTP Settings.
2. Click New SMTP, or select an existing config from the list.
3. Fill in the fields in the field reference.
4. Click Save. Success confirms the configuration is stored.
5. Prefer Send test email before marking a new config as default or assigning it to teams.

Send a test email

1. Select a saved configuration (not an unsaved new form).
2. Open the test-email action and enter a recipient address you can check.
3. Confirm the message arrives from the expected Sender email / Sender name.

If the test fails, the UI shows the error detail from the SMTP attempt (auth failure, connection refused, TLS mismatch, and similar). Fix host/port/security/credentials and test again.

Platform default

Exactly one active configuration can be the platform default.

1. Select the config you want as default.
2. Choose Make default and confirm.

Teams without an SMTP override use this default. Changing the default updates mail for every team still set to Platform default.

Assign SMTP per team

1. Open Super Admin → Teams → select the team → Settings → Edit Settings.
2. Under SMTP Configuration, choose:
   • Platform default (currently <name>) — inherit the current default and follow future default changes, or
   • A specific named configuration — pin that team to that sender even if the platform default changes.
3. Save team settings.

Resolution order

1. If the team has a pinned smtp_config_id and that config is still active → use it.
2. Otherwise → use the platform default.
3. If a pinned config is missing or deactivated → fall back to the platform default.

Team list views may show the effective sender email next to the SMTP label when an override is set.

Deactivate a configuration

Deactivating soft-deactivates the config (it leaves the active list; it is not a hard purge of history).

• Prefer switching teams and the platform default before deactivating a sender that is still in use.
• Keep at least one healthy Default when you rely on platform email.

Email templates

On the Templates tab you can edit platform email templates (subject and body). Preview and reset-to-default actions are available per template where supported. Templates render through the SMTP path resolved for the relevant team (or the platform default).

Password reset (on-premises)

Password reset emails are sent through the configured SMTP path, with reset links routed through the backend so they work correctly in on-premises deployments. If SMTP is missing or misconfigured, reset mail fails (callers may see a service-unavailable style error). Configure and test SMTP before relying on self-service reset in on-prem.

Typical setups

Setup	Approach
Single corporate relay	One config, mark it Default; leave all teams on platform default
Shared vs tenant senders	Default for most teams; override high-touch tenants to their own SMTP
Migrate providers	Add the new config → test → switch Default → remove per-team overrides that still point at the old host → deactivate the old config

Troubleshooting

Symptom	What to check
Test email fails	Host/port reachable from the EKB backend; TLS vs SSL; username/password; provider app-password / IP allowlist
Team still sends from the wrong address	Team SMTP Configuration override vs platform default; whether the intended config is Active and Default
Password reset mail never arrives (on-prem)	Platform default SMTP exists and passes a test; spam folders; sender domain SPF/DKIM at the provider
Cannot clear password	Use Clear saved password, then Save
SMTP toolkit works but platform mail does not	Expected — toolkit credentials are separate from Email Configuration

Related

• Teams — team settings, including SMTP override
• RBAC — Email Configuration is Super Admin–only
• Workflow failure notifications — requires SMTP for the team (on-premises)