Send a test email
POST /admin/system/smtp/test
Tries to send one test email and reports the outcome. Nothing is queued or retried: the call waits for the attempt, and each call makes a new one.
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 a to that isn’t a valid email address,
gets a plain-text 400, even when you aren’t signed in. Otherwise
signed-out callers get 401 and callers without the permission 403.
The body is optional.
The email goes to to if you give one; only the bare address is
kept, without a display name, and any address is accepted. Otherwise
it goes to the email address saved on your own account, read when
you call; if there is none, you get 400. This call saves nothing,
and settings that haven’t been saved aren’t used.
What happens next depends on a mode set when the server starts,
reported in mode:
smtp: the server reads the saved SMTP settings and sends the email through the relay. With no saved host you get 503. Any other failure, such as a connection, sign-in or address problem, gets 400 with the server’s or relay’s message inerror. A 200 means the relay accepted the email, not that it reached the inbox.capture: the email is kept in the server’s memory and never sent.disabled: the email is dropped and never sent; the server log records only its recipient and subject.
In capture and disabled mode the call answers 200 with sent
true although nothing is delivered, so check mode and message.
Connecting to the relay gives up after 30 seconds, but once
connected there is no overall time limit. The email uses the shipped
test template, or your own version of it if one is saved and works.
Server errors get a plain-text 500.
Authorizations
Section titled “Authorizations ”Request Body
Section titled “Request Body ”object
Who to send the test to. Only the bare address is kept, without a display name. When it’s left out, the email goes to the address saved on your account.
Responses
Section titled “ Responses ”The send step finished without an error. Only smtp mode means the email left the server.
object
Always true in a 200 response: the send step finished without an error. It doesn’t mean the email was delivered.
The sending mode set when the server started: smtp sends through the relay, capture keeps the email in memory without sending it, and disabled drops it, logging only its recipient and subject.
The address chosen for the test. It doesn’t show that the email was sent or delivered.
A short summary of what happened to the email, such as handed to SMTP relay.
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 completedThe server is in smtp mode and no SMTP host is saved.
object
Human-readable error summary
Example
the request could not be completed