---
title: "Test SMTP Connection"
description: "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

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

## Example (cURL): Testing new credentials

```bash
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)

```json
{
  "success": true,
  "messageId": "<abc123@mail.deinkunde.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