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.example.com",
    "port": 587,
    "tlsMode": "starttls",
    "username": "alerts@example.com",
    "password": "secret-password",
    "fromName": "Uptimeify Alerts",
    "fromEmail": "alerts@example.com",
    "toEmail": "admin@example.com"
  }'

Response (success)

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

Common errors

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