1. API
  2. Admin
  3. SMTP configuration

SMTP configuration: Get

Last updated Open markdown version

Description

Retrieve the SMTP configuration used by your self-hosted tenant to send email.

This endpoint is only available on self-hosted tenants. If no configuration has been set through the API, the response returns the SMTP settings from the tenant environment.

Request

HTTP Method: GET

Sample request

curl -X GET \
  --proto '=https' --tlsv1.2 \
  https://<tenant-domain>/api/v1/admin/smtp \
  -H 'content-type: application/json' \
  -H 'Authorization: Bearer <<CREDENTIAL.tines_api_key>>'

Response

A successful request will return a JSON object describing the current SMTP configuration. The password is never returned. Use password_set to check whether a password is configured.

When source is environment, the response uses the same shape as API-managed settings, but values are loaded from the tenant environment instead of the database. Configuration warnings are only returned for API-managed database settings.

Field description

Parameter Description
address SMTP server address.
port SMTP server port.
domain Domain sent during the SMTP greeting.
user_name User name used for SMTP authentication.
auth_type Authentication mode. Supported values are plain, login, and cram_md5.
encryption_mode Encryption mode. Supported values are none, tls, starttls_auto, and starttls_strict.
verify_ssl_certificate Boolean flag indicating whether TLS certificates are verified.
ca_path Path to a directory of CA certificates on the self-hosted installation.
ca_file Path to a CA certificate file on the self-hosted installation.
open_timeout SMTP connection open timeout in seconds.
read_timeout SMTP connection read timeout in seconds.
source Indicates where the current settings were loaded from. database means the tenant is using settings saved through this API. environment means no API-managed configuration exists, so Tines is using SMTP settings from the tenant environment.
password_set Boolean flag indicating whether a password is configured.
warnings Optional object describing configuration warnings by field.

Configuration notes

Use encryption_mode to control how Tines secures the SMTP connection:

  • none: Connect without TLS or STARTTLS.
  • tls: Use direct TLS from the start of the SMTP connection. This is typically used with port 465.
  • starttls_auto: Use STARTTLS when the SMTP server advertises support for it. If the server does not advertise STARTTLS, continue without TLS.
  • starttls_strict: Require STARTTLS. The connection fails if the SMTP server does not advertise STARTTLS.

Port 587 is typically used with starttls_auto or starttls_strict.

STARTTLS modes begin with a plain SMTP connection, then upgrade the connection with the STARTTLS command. If the server advertises STARTTLS but TLS negotiation or certificate verification fails, the connection fails.

When verify_ssl_certificate is false, Tines does not verify the SMTP server's TLS certificate. Default system certificates and any ca_path or ca_file values are not used to verify trust. When both ca_path and ca_file are provided, ca_file takes precedence.

Use auth_type to control how Tines authenticates to the SMTP server:

  • plain: Send the user name and password together in one SMTP authentication command.
  • login: Send the user name and password in separate SMTP authentication steps.
  • cram_md5: Use challenge-response authentication instead of sending the password directly.

Sample response

{
  "address": "smtp.example.com",
  "port": 587,
  "domain": "example.com",
  "user_name": "smtp-user",
  "auth_type": "plain",
  "encryption_mode": "starttls_auto",
  "verify_ssl_certificate": true,
  "ca_path": null,
  "ca_file": null,
  "open_timeout": 30,
  "read_timeout": 30,
  "source": "database",
  "password_set": true
}

Errors

This endpoint is only allowed for self-hosted tenants.

Status Meaning
403 The endpoint was called on a Tines cloud tenant.
Was this helpful?