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,encryptionandfrom_addressare saved as sent, without trimming. A missing one is saved empty, or as 0 for the port.username: leaving it out or sendingnullclears the saved user name.password: leaving it out, or sendingnullor an empty string, keeps the saved password, so it can’t be cleared here. Any other value replaces it and is stored encrypted.password_setand 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.
Authorizations
Section titled “Authorizations ”Request Body required
Section titled “Request Body required ”object
Example
smtp.example.comExample
587Example
starttlsWrite-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.
True when a password is currently stored. Set by the server on GET responses; ignored if sent on PATCH.
Example
ArtSite <noreply@example.com>Responses
Section titled “ Responses ”The SMTP settings as this call saved them, without the password.
object
Example
smtp.example.comExample
587Example
starttlsWrite-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.
True when a password is currently stored. Set by the server on GET responses; ignored if sent on PATCH.
Example
ArtSite <noreply@example.com>Malformed request
object
Human-readable error summary
Example
the request could not be completedAuthentication required, missing, or invalid
object
Human-readable error summary
Example
the request could not be completedExample
{ "error": "authentication required: sign in and retry with a valid session or API token"}Authenticated but missing required capabilities
object
Human-readable error summary
Example
the request could not be completed