Skip to content

Get the SMTP settings

GET
/admin/system/smtp

Returns the saved settings the server uses to send email through SMTP, without the password; password_set says whether one is saved.

You need system.config.read or system.admin for the whole install; a permission held only for a team doesn’t count. Without one you get 403, and signed-out callers get 401.

The values are read from the database on each call. password_set only means a password is saved, not that it works. username is left out when it is empty. A fresh install has an empty host, port 587 and starttls. With no host saved, the other fields weren’t checked when they were saved, so they can hold values outside the declared ones, such as an empty encryption. These settings don’t say whether the server sends email at all; that depends on a mode set when it starts, which sendSMTPTestEmail reports. Server errors, including settings or a password that can’t be read, get a plain-text 500.

The saved SMTP settings, without the password.

object
host
required
string
Example
smtp.example.com
port
required
integer
Example
587
encryption
required
string
Allowed values: none starttls tls
Example
starttls
username
string
password

Write-only. Provide to set or rotate the SMTP password; omit (or send empty string) on PATCH to keep the current value. The response never echoes this field — read password_set instead to check whether one is on file. Stored at rest encrypted via the AA_MASTER_KEY-backed atrest package; never sent back to clients.

string format: password
password_set

True when a password is currently stored. Set by the server on GET responses; ignored if sent on PATCH.

boolean
from_address
required
string
Example
ArtSite <noreply@example.com>

Authentication required, missing, or invalid

object
error
required

Human-readable error summary

string
Example
the request could not be completed
Example
{
"error": "authentication required: sign in and retry with a valid session or API token"
}

Authenticated but missing required capabilities

object
error
required

Human-readable error summary

string
Example
the request could not be completed