Send test email
curl --request POST \ --url http://localhost:9090/api/v1/admin/settings/email/send-test \ --header 'Authorization: Bearer <token>' \ --header 'Content-Type: application/json' \Send a short message to to through the stored SMTP settings, the stored password
included, to check what a save’s connection does not: the encryption, the certificate,
the credentials and the sender. Answers 200 once the SMTP server has accepted the
message, with encrypted saying whether it went over TLS.
The message is the test email template, in the built-in language that matches the
caller’s and in the default brand. A send is audited as sent_test_email, naming the
test template and that language.
With smtpEncryption set to none, STARTTLS if available, a message the SMTP server
can’t take over TLS, with a certificate the auth server trusts for smtpHost, is sent
unencrypted, and encrypted is false. Each such send writes an Info record to the auth
server’s log, “sending the email unencrypted”, whose reason is starttls_not_offered,
starttls_refused, starttls_failed or tls_failed.
The send waits up to 10 seconds to connect, including the TLS handshake for SSL/TLS. After that, each step of the SMTP conversation fails if the SMTP server sends or takes nothing for 20 seconds, and the whole send ends 40 seconds after it started connecting.
Authorizations
Section titled “Authorizations”Request Bodyrequired
Section titled “Request Bodyrequired”object
Example generated
{}Responses
Section titled “Responses”Test email sent
object
Whether the message went to the SMTP server over TLS. Always true for ssltls and
starttls. For none, STARTTLS if available, true when the upgrade through STARTTLS
succeeded, and false when the server didn’t offer STARTTLS or the upgrade failed, so
the message was sent unencrypted; the auth server’s log has the reason.
Example generated
{ "success": true, "encrypted": true}Error_code is SMTP_NOT_ENABLED while SMTP is disabled, INVALID_REQUEST_BODY for a
body that will not parse, handler.settings_email.destination_required when to is missing,
validator.email.invalid_format when it is not an email address, and SEND_FAILED when
the send fails.
A SEND_FAILED answers one of these fixed messages, chosen by what failed:
- “Unable to send the test email: host name not found.” Check the host name, as for a save.
- “Unable to send the test email: connection timed out.” Check the port and any firewall, as for a save. A server that accepted the connection and then went quiet also ends here, which is what STARTTLS or STARTTLS if available against an SSL/TLS port such as 465 looks like.
- “Unable to send the test email: connection refused.” Check the port.
- “The SMTP server did not offer STARTTLS; check the port, or choose STARTTLS if available only if the server has no TLS.” The encryption is STARTTLS and the server does not offer it. Goiabada does not continue unencrypted.
- “With STARTTLS if available, the password is sent only to a server on this machine; set the encryption to STARTTLS or SSL/TLS.”
The encryption is STARTTLS if available, a username is set, and the server
offers PLAIN or LOGIN, which send the password itself. That is refused before
any AUTH command whether or not the connection was upgraded to TLS. Only a
server on
localhost,127.0.0.1or::1is exempt. - “SMTP credentials are configured but the server offers no authentication.” A username is set and the server offers no AUTH: the wrong host or port, or a server that offers authentication only over TLS, reached with STARTTLS if available when the TLS handshake failed.
- “The SMTP server offers none of PLAIN, LOGIN or CRAM-MD5.” The server offers only mechanisms Goiabada does not implement, such as XOAUTH2: use a password the server accepts through one of these three, often called an app password or an SMTP key.
- “The SMTP username and password can’t be used with the server’s sign-in method: the password is empty, or one of them contains a null character.” The server offers PLAIN, and the stored credentials are ones it can’t carry: a username is set and the password is empty, or the username or password holds a null character or bytes that aren’t valid UTF-8. Nothing is sent to the server. Set a password, or retype the username and password.
- “The TLS connection failed; check the encryption setting and the server’s certificate.”
SSL/TLS against a port that expects STARTTLS, such as 587; a certificate the auth
server does not trust, that has expired, or that names a host other than
smtpHost; or a server that refused the STARTTLS command. Certificates are always verified. With STARTTLS if available, these send the message unencrypted instead. - “The SMTP server rejected the username or password.” Check the username and password.
- “The SMTP server refused the message.” The server refused the sender, the
recipient or the message itself, most often because the account may not send
from
smtpFromEmail. - “Unable to send the test email.” Any other failure: a connection that dropped
partway through the conversation, a network the auth server has no route to,
or a stored password the auth server cannot decrypt, such as one encrypted under
a
GOIABADA_AES_ENCRYPTION_KEYit no longer has.
Nothing from the error itself is answered, no address, operating-system error or server reply; the full error goes to the auth server’s log, at Warn, as “unable to send the test email” under the request’s request_id.
Admin/account API error envelope. Routing by HTTP status code: 4xx is a client-correctable failure (validation, not found, permission denied, rate limited); 5xx is a server-side problem. The body provides a stable error_code and an error_description for people to read. Protocol endpoints (/auth/token, /auth/authorize, /connect/register, /userinfo) use their RFC-defined error envelopes instead of this one.
object
Stable identifier for the failure. UPPER_SNAKE for legacy codes (e.g. VALIDATION_ERROR), dotted lowercase for codes named after the sentence’s catalog key (e.g. validator.email.required). Never translated, whatever the request’s language.
A sentence for people to read: in the request’s language, from the ui_locales query parameter or else the Accept-Language header, when the server has the sentence in that language, and in English otherwise. Route on error_code, not on this text.
A JSON Pointer (RFC 6901) to the member of the request body the refusal is about,
such as /footerLinks/1/url, /footerLinks/0/labels/pt-BR or /palette/light/brand.
Left out when the refusal names no member. It’s set by the refusals of a brand’s footer
links, palette and custom CSS, and of an email template’s text and brandId.
Example generated
{ "error_code": "example", "error_description": "example", "error_field": "example"}Missing or invalid access token (ACCESS_TOKEN_REQUIRED, INVALID_TOKEN), or a refused DPoP proof (INVALID_DPOP_PROOF)
Admin/account API error envelope. Routing by HTTP status code: 4xx is a client-correctable failure (validation, not found, permission denied, rate limited); 5xx is a server-side problem. The body provides a stable error_code and an error_description for people to read. Protocol endpoints (/auth/token, /auth/authorize, /connect/register, /userinfo) use their RFC-defined error envelopes instead of this one.
object
Stable identifier for the failure. UPPER_SNAKE for legacy codes (e.g. VALIDATION_ERROR), dotted lowercase for codes named after the sentence’s catalog key (e.g. validator.email.required). Never translated, whatever the request’s language.
A sentence for people to read: in the request’s language, from the ui_locales query parameter or else the Accept-Language header, when the server has the sentence in that language, and in English otherwise. Route on error_code, not on this text.
A JSON Pointer (RFC 6901) to the member of the request body the refusal is about,
such as /footerLinks/1/url, /footerLinks/0/labels/pt-BR or /palette/light/brand.
Left out when the refusal names no member. It’s set by the refusals of a brand’s footer
links, palette and custom CSS, and of an email template’s text and brandId.
Example generated
{ "error_code": "example", "error_description": "example", "error_field": "example"}Headers
Section titled “Headers”A Bearer challenge, then a DPoP challenge naming the accepted proof algorithms, on
token refusals, the error in the challenge of the scheme the token was sent with:
Bearer realm="goiabada", error="invalid_token", error_description="...", DPoP realm="goiabada", algs="ES256 ...". An operation may also return a handler-level
401 without this header.
The token is valid but does not authorise this request. A caller tells the refusals apart by error_code.
INSUFFICIENT_SCOPE comes from the route’s authorisation middleware,
before the handler runs: an Admin operation needs one of the scopes
its route names, and an Account operation needs
authserver:manage-account.
USER_CONTEXT_REQUIRED comes from the same middleware on the Account operations, which also require the token to have been issued for a user: one obtained through the client credentials grant carries no auth_time claim and is refused here.
FORBIDDEN comes from the handler, on the account endpoints that resolve a resource by id and then check it belongs to the caller, so a valid token for the wrong user reaches this rather than a 404.
CLIENT_NOT_ALLOWED comes from the route on the two Account
operations only the admin console’s own client may call,
deleteAccount and exportAccount. ACCOUNT_DELETION_DISABLED comes
from deleteAccount while an administrator has turned off Let
users delete their own account.
MANAGE_SCOPE_REQUIRED comes from the handler, on the Admin operations
the administrative policy guards. Only authserver:manage creates an
administrator, changes one, or changes what reaches one, so no
granular scope will ever be enough: the remedy is a token holding
authserver:manage, not requesting the route’s scope as for
INSUFFICIENT_SCOPE. An administrator is a user, group or client
holding any of the six administrative permissions (manage,
admin-read, manage-users, manage-clients, manage-settings,
browser-sessions), a user directly or through any of its groups,
the admin console’s own client whatever it holds, and a client
allowed to request the administrative scopes. A granular scope is
refused here when it:
- grants or revokes an administrative permission, directly or by moving a user into or out of a group that holds one, or deletes such a group;
- writes to an administrator user (profile, credentials, enabled, sessions, consents, attributes, memberships, permissions, deletion), an administrative group (settings, attributes, members, permissions, deletion), or an administrator client (settings, authentication, flows, redirect URIs, sign-out redirect URIs, back-channel logout, DPoP, web origins, token settings, permissions, introspection resources, logo, deletion);
- switches whether a client may request the administrative scopes, on or off, on any client;
- adds the
authserverresource to a client’s introspection resources; - reads an administrator client’s secret, or reads or sets the
secret of a client listed for the
authserverresource among its introspection resources; - sets or changes a client’s back-channel logout URI;
- changes the email or the audit-log settings;
- changes an administrative permission’s description.
Granular scopes still read administrators. The refusal is answered
after the request’s 400 and 404, writes nothing, carries the insufficient_scope challenge of
the scheme the token was sent with, such as
WWW-Authenticate: Bearer realm="goiabada", error="insufficient_scope", error_description="...", scope="authserver:manage", and leaves anadministrator_change_refusedaudit record.
Admin/account API error envelope. Routing by HTTP status code: 4xx is a client-correctable failure (validation, not found, permission denied, rate limited); 5xx is a server-side problem. The body provides a stable error_code and an error_description for people to read. Protocol endpoints (/auth/token, /auth/authorize, /connect/register, /userinfo) use their RFC-defined error envelopes instead of this one.
object
Stable identifier for the failure. UPPER_SNAKE for legacy codes (e.g. VALIDATION_ERROR), dotted lowercase for codes named after the sentence’s catalog key (e.g. validator.email.required). Never translated, whatever the request’s language.
A sentence for people to read: in the request’s language, from the ui_locales query parameter or else the Accept-Language header, when the server has the sentence in that language, and in English otherwise. Route on error_code, not on this text.
A JSON Pointer (RFC 6901) to the member of the request body the refusal is about,
such as /footerLinks/1/url, /footerLinks/0/labels/pt-BR or /palette/light/brand.
Left out when the refusal names no member. It’s set by the refusals of a brand’s footer
links, palette and custom CSS, and of an email template’s text and brandId.
Example generated
{ "error_code": "example", "error_description": "example", "error_field": "example"}Headers
Section titled “Headers”An insufficient_scope challenge in the scheme the token was sent with, Bearer or DPoP, on every refusal but FORBIDDEN and ACCOUNT_DELETION_DISABLED, which omit it.
The request failed inside the server, most often a storage error. error_code is INTERNAL_SERVER_ERROR: no detail about the failure, only the request id an operator can find the log line by, and retrying is reasonable. Key rotation’s 500 also answers KEY_SET_INCOMPLETE, which names its cause and no retry clears.
Admin/account API error envelope. Routing by HTTP status code: 4xx is a client-correctable failure (validation, not found, permission denied, rate limited); 5xx is a server-side problem. The body provides a stable error_code and an error_description for people to read. Protocol endpoints (/auth/token, /auth/authorize, /connect/register, /userinfo) use their RFC-defined error envelopes instead of this one.
object
Stable identifier for the failure. UPPER_SNAKE for legacy codes (e.g. VALIDATION_ERROR), dotted lowercase for codes named after the sentence’s catalog key (e.g. validator.email.required). Never translated, whatever the request’s language.
A sentence for people to read: in the request’s language, from the ui_locales query parameter or else the Accept-Language header, when the server has the sentence in that language, and in English otherwise. Route on error_code, not on this text.
A JSON Pointer (RFC 6901) to the member of the request body the refusal is about,
such as /footerLinks/1/url, /footerLinks/0/labels/pt-BR or /palette/light/brand.
Left out when the refusal names no member. It’s set by the refusals of a brand’s footer
links, palette and custom CSS, and of an email template’s text and brandId.
Example generated
{ "error_code": "example", "error_description": "example", "error_field": "example"}