Skip to content

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 in error. 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.

object
to

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.

string format: email

The send step finished without an error. Only smtp mode means the email left the server.

object
sent
required

Always true in a 200 response: the send step finished without an error. It doesn’t mean the email was delivered.

boolean
mode
required

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.

string
Allowed values: smtp capture disabled
recipient
required

The address chosen for the test. It doesn’t show that the email was sent or delivered.

string
message

A short summary of what happened to the email, such as handed to SMTP relay.

string

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

The server is in smtp mode and no SMTP host is saved.

object
error
required

Human-readable error summary

string
Example
the request could not be completed