1. API
  2. Admin
  3. SMTP configuration

SMTP configuration: Update

Last updated Open markdown version

Description

Create or replace the SMTP configuration used by your self-hosted tenant to send email.

This endpoint is only available on self-hosted tenants. The request replaces the full SMTP configuration and does not update individual fields, so include every value you want to keep. Optional fields that are omitted are cleared, except open_timeout and read_timeout, which default to 30 seconds when omitted.

Because the password is never returned by the GET endpoint, it must be included whenever you save a configuration that uses SMTP authentication. Existing passwords are not preserved automatically during replacement.

Request

HTTP Method: PUT

Field description

Parameter Required Description
address Yes SMTP server address. Maximum length: 255 characters.
port Yes SMTP server port. Must be an integer from 1 to 65535.
domain No Domain sent during the SMTP greeting. Maximum length: 255 characters.
user_name No User name used for SMTP authentication. Maximum length: 255 characters.
password No Password used for SMTP authentication. Maximum length: 1024 characters.
auth_type No Authentication mode. Supported values are plain, login, and cram_md5.
encryption_mode Yes Encryption mode. Supported values are none, tls, starttls_auto, and starttls_strict.
verify_ssl_certificate Yes Boolean flag indicating whether TLS certificates are verified.
ca_path No Path to a directory of CA certificates on the self-hosted installation. Maximum length: 4096 characters.
ca_file No Path to a CA certificate file on the self-hosted installation. Maximum length: 4096 characters.
open_timeout No SMTP connection open timeout in seconds. Must be an integer from 1 to 120. Default is 30.
read_timeout No SMTP connection read timeout in seconds. Must be an integer from 1 to 120. Default is 30.

If auth_type is set, user_name and password are required. If auth_type is omitted or null, Tines does not attempt SMTP authentication. If either user_name or password is set without auth_type, both values must be provided.

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 request

curl -X PUT \
  --proto '=https' --tlsv1.2 \
  https://<tenant-domain>/api/v1/admin/smtp \
  -H 'content-type: application/json' \
  -H 'Authorization: Bearer <<CREDENTIAL.tines_api_key>>' \
  -d '{
       "address": "smtp.example.com",
       "port": 587,
       "domain": "example.com",
       "user_name": "smtp-user",
       "password": "smtp-password",
       "auth_type": "plain",
       "encryption_mode": "starttls_auto",
       "verify_ssl_certificate": true,
       "ca_path": null,
       "ca_file": null,
       "open_timeout": 30,
       "read_timeout": 30
      }'

Response

A successful request will return an empty response with a 200 status code.

If the configuration is saved but has warnings, the request will return a 200 status code with a JSON object describing the warnings.

Sample response with warnings

{
  "warnings": {
    "ca_path": ["Ca path will be ignored because ca_file takes precedence"]
  }
}

Errors

Errors are returned as a JSON object, along with an appropriate HTTP status code:

Status Meaning
403 The endpoint was called on a Tines cloud tenant.
422 Invalid SMTP configuration, including missing required fields or invalid values.

Example validation error response

{
  "errors": {
    "port": ["Port can't be blank"],
    "encryption_mode": ["Encryption mode can't be blank"],
    "verify_ssl_certificate": ["Verify ssl certificate must be true or false"]
  }
}
Was this helpful?