Skip to content

Replace the SMTP settings

PATCH
/admin/system/smtp

Replaces the saved SMTP settings and returns the result. Only the password is merged; every other field is taken from the body, so send them all each time.

You need system.config.write or system.admin for the whole install; a permission held only for a team doesn’t count. A body that isn’t valid JSON, or has a field of the wrong type such as a port sent as a string, gets a plain-text 400, even when you aren’t signed in. Otherwise signed-out callers get 401 and callers without the permission 403.

  • host, port, encryption and from_address are saved as sent, without trimming. A missing one is saved empty, or as 0 for the port.
  • username: leaving it out or sending null clears the saved user name.
  • password: leaving it out, or sending null or an empty string, keeps the saved password, so it can’t be cleared here. Any other value replaces it and is stored encrypted.
  • password_set and unknown fields are ignored.

When host isn’t empty, encryption must be none, starttls or tls and port 1 to 65535, or you get 400 with the reason in error. With an empty host nothing else is checked, and sending through SMTP stops. Nothing checks that the host can be reached, that the sender address is valid, or that the user name and password work, and saving sends nothing; sendSMTPTestEmail tries the saved settings. With encryption none and a user name, sending works only through a relay named localhost, 127.0.0.1 or ::1, because the server won’t send the password over an unencrypted connection to any other host. An error while saving also gets 400 with the reason in error.

The saved settings are read first; if that fails you get a plain-text 500 and nothing is saved. Two saves made at the same time can overwrite each other, because each starts from the settings it read: the later one can bring back an older password or undo the other’s changes. The response shows what this call wrote, not a fresh read, and never includes the password. Saved settings apply to the next email sent through SMTP; they don’t change whether the server sends email at all, which is set when it starts.

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>

The SMTP settings as this call saved them, 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>

Malformed request

object
error
required

Human-readable error summary

string
Example
the request could not be completed

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