--- title: Update url: https://www.tines.com/docs/api/admin/smtp/update/ updated: 2026-07-10T16:25:15+00:00 description: Create or replace the SMTP configuration used by your self-hosted tenant to send email. --- *[tines.com](https://www.tines.com/llms.txt) › [Docs](https://www.tines.com/docs/llms.txt) › [Tines API](https://www.tines.com/docs/api/llms.txt) › [Admin](https://www.tines.com/llm/docs/api/admin.md) › [SMTP configuration](https://www.tines.com/llm/docs/api/admin/smtp.md)* # Update *[View on tines.com](https://www.tines.com/docs/api/admin/smtp/update/)* ## 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 ```bash curl -X PUT \ --proto '=https' --tlsv1.2 \ https:///api/v1/admin/smtp \ -H 'content-type: application/json' \ -H 'Authorization: Bearer <>' \ -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 ```json { "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 ```json { "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"] } } ```