Admin API: SMTP

Operations on smtp in the Odudu admin API, one section each. Every request carries a bearer token; the index says which audience it needs and how a refusal is shaped.

GET /admin/tenants/{tenant}/smtp

Requires the "manage-tenant" capability.

effective names whose relay the tenant’s mail goes through: tenant for its own, deployment for the deployment’s ODUDU_SMTP_* sender, none when mail is only logged.

Path parameters

Name	Type	Required	Details
tenant	string	yes	The tenant being administered, addressed by name.

Responses

200 OK

Body: application/json

Field	Type	Required	Details
configured	boolean	yes	Whether the tenant has a relay of its own saved.
host	string or null	yes	The relay’s host, or null when the tenant has none.
port	integer or null	yes	The relay’s port, or null when the tenant has none.
from_address	string or null	yes	What the From line of each message says, or null when the tenant has no relay.
username	string or null	yes	The login the relay asks for, or null when it asks for none.
password_set	boolean	yes	Whether a password is stored. The password itself is never returned, whether the relay was just written or read in an earlier session.
starttls	boolean or null	yes	Whether the connection must upgrade to TLS (STARTTLS), or null when the tenant has no relay.
effective	string	yes	Constraints: one of tenant, deployment, none.

401 RFC 9457 problem details

Body: application/problem+json, an RFC 9457 problem document described under problem details.

403 RFC 9457 problem details

Body: application/problem+json, an RFC 9457 problem document described under problem details.

PUT /admin/tenants/{tenant}/smtp

Requires the "manage-tenant" capability.

Replaces the whole configuration except the password, which GET never hands back to resend: omitting password keeps the stored one, and null clears it. A kept password stays with the relay it was entered for: omitting it while host, port or username changes is refused with 400 naming password. Answers an ETag, as GET does; If-Match is optional, and a stale one is refused with 412.

Path parameters

Name	Type	Required	Details
tenant	string	yes	The tenant being administered, addressed by name.

Request body

Body: application/json

Field	Type	Required	Details
host	string	yes	The relay’s host. Constraints: at least 1 character.
port	integer	yes	The relay’s port, a whole number from 1 to 65535. Constraints: at least 1, at most 65535.
from_address	string	yes	What the From line of each message says. Constraints: at least 1 character.
username	string or null	no	The login the relay asks for. Omit it or send null when it asks for none. Constraints: at least 1 character.
password	string or null	no	The password to store. Omitted, the stored one is kept while the host, port and username are unchanged; null clears it. Constraints: at least 1 character.
starttls	boolean	no	Whether the connection must upgrade to TLS (STARTTLS). Required while a username or password is set.

Responses

200 OK

Body: application/json

Field	Type	Required	Details
configured	boolean	yes	Whether the tenant has a relay of its own saved.
host	string or null	yes	The relay’s host, or null when the tenant has none.
port	integer or null	yes	The relay’s port, or null when the tenant has none.
from_address	string or null	yes	What the From line of each message says, or null when the tenant has no relay.
username	string or null	yes	The login the relay asks for, or null when it asks for none.
password_set	boolean	yes	Whether a password is stored. The password itself is never returned, whether the relay was just written or read in an earlier session.
starttls	boolean or null	yes	Whether the connection must upgrade to TLS (STARTTLS), or null when the tenant has no relay.
effective	string	yes	Constraints: one of tenant, deployment, none.

401 RFC 9457 problem details

Body: application/problem+json, an RFC 9457 problem document described under problem details.

403 RFC 9457 problem details

Body: application/problem+json, an RFC 9457 problem document described under problem details.

DELETE /admin/tenants/{tenant}/smtp

Requires the "manage-tenant" capability.

Removes the tenant’s own relay, sending its mail back to the deployment’s own sender. 404 when the tenant has no SMTP configuration.

Path parameters

Name	Type	Required	Details
tenant	string	yes	The tenant being administered, addressed by name.

Responses

204 OK

Body: application/json

Field	Type	Required	Details
(body)	any	yes

401 RFC 9457 problem details

Body: application/problem+json, an RFC 9457 problem document described under problem details.

403 RFC 9457 problem details

Body: application/problem+json, an RFC 9457 problem document described under problem details.

POST /admin/tenants/{tenant}/smtp/test

Requires the "manage-tenant" capability.

Sends one message synchronously and reports the transport’s own failure as a 502, rather than the tenant discovering a bad configuration only when a user’s verification mail silently fails. 400 when the tenant has no SMTP configuration.

Path parameters

Name	Type	Required	Details
tenant	string	yes	The tenant being administered, addressed by name.

Request body

Body: application/json

Field	Type	Required	Details
to	string	yes	The address to send the test message to. Constraints: at least 1 character.

Responses

200 OK

Body: application/json

Field	Type	Required	Details
sent	boolean	yes	True when the relay accepted the message. A relay that refuses it answers 502 instead.

401 RFC 9457 problem details

Body: application/problem+json, an RFC 9457 problem document described under problem details.

403 RFC 9457 problem details

Body: application/problem+json, an RFC 9457 problem document described under problem details.

Documentation coverage: 22 of 24 fields described (91%).