Test SMTP Connection

Tests the SMTP configuration by sending a test email. All parameters are optional. When omitted, stored config values are used. This allows testing new credentials before saving them. Admin-only.

POST /api/organization/smtp/test

The test also updates the SMTP config's lastTestedAt, lastTestStatus, and lastTestError fields.

Request Body (all optional)

Field	Type	Description
`toEmail`	string	Recipient email address (max 320 chars). Defaults to current user's email.
`subject`	string	Email subject (1-200 chars). Defaults to `SMTP Test (<timestamp>)`.
`message`	string	Email body (1-2000 chars). Defaults to a standard test message.
`host`	string\|null	SMTP server hostname (1-255 chars). Overrides stored config.
`port`	number\|null	SMTP server port (1-65535). Overrides stored config.
`username`	string\|null	SMTP username (1-200 chars). Overrides stored config.
`password`	string\|null	SMTP password (1-500 chars). Overrides stored config (not persisted).
`tlsMode`	string\|null	`ssl`, `starttls`, or `none`. Overrides stored config.
`fromName`	string\|null	Sender display name (1-200 chars). Overrides stored config.
`fromEmail`	string\|null	Sender email address (max 320 chars). Overrides stored config.
`replyTo`	string\|null	Reply-to email address (max 320 chars). Overrides stored config.

Example (cURL): Using stored config

curl -X POST "$BASE_URL/api/organization/smtp/test" \
  -H "Cookie: $SESSION_COOKIE" \
  -H "Content-Type: application/json" \
  -d '{}'

Example (cURL): Testing new credentials

curl -X POST "$BASE_URL/api/organization/smtp/test" \
  -H "Cookie: $SESSION_COOKIE" \
  -H "Content-Type: application/json" \
  -d '{
    "host": "smtp.deinkunde.com",
    "port": 587,
    "tlsMode": "starttls",
    "username": "alerts@deinkunde.com",
    "password": "secret-password",
    "fromName": "Uptimeify Alerts",
    "fromEmail": "alerts@deinkunde.com",
    "toEmail": "admin@deinkunde.com"
  }'

Response (success)

{
  "success": true,
  "messageId": "<abc123@mail.deinkunde.com>"
}

Common errors

400 Password must be re-entered when the SMTP host changes (data.code: smtpPasswordRequiredForNewHost) when the request sends a host that differs from the stored one but no password: the stored password is only ever sent to the stored host
400 Missing recipient email (toEmail) when no recipient and user has no email
400 SMTP config incomplete (host/port required) when host or port is missing
400 SMTP config incomplete (username required) when username is needed but missing
400 SMTP password missing (username is set) when password is needed but missing
400 SMTP config incomplete (fromEmail required) when fromEmail is missing
403 Forbidden when not an admin
502 Failed to send SMTP test email when the SMTP connection fails

Test SMTP Connection

Request Body (all optional)Copy Anchor Link

Example (cURL): Using stored configCopy Anchor Link

Example (cURL): Testing new credentialsCopy Anchor Link

Response (success)Copy Anchor Link

Common errorsCopy Anchor Link

On this page

Request Body (all optional)

Example (cURL): Using stored config

Example (cURL): Testing new credentials

Response (success)

Common errors