Skip to Content
Uptimeify Docs
MonitorsSmtp monitors

Create SMTP Monitor

Creates a new SMTP monitor.

POST /api/smtp-monitors

Authentication

Requires a valid session.

  • Header: Authorization: Bearer <token>

Request Body

{
  "customerId": "11111111-1111-4111-8111-111111111111",
  "name": "Outbound SMTP",
  "hostname": "smtp.deinkunde.com",
  "port": 587,
  "status": "active",
  "checkInterval": 60,
  "timeoutSeconds": 30,
  "smtpConfig": {
    "secure": false,
    "ignoreTls": false,
    "requireTls": false,
    "auth": {
      "user": "username",
      "pass": "password"
    }
  }
}

Fields

  • customerId (number | string, required)
    • Accepts either the internal numeric customer ID or the public customer UUID.
  • name (string, required)
  • hostname (string, required)
    • Must be a hostname only (no protocol like https://, no path like /smtp).
  • port (number | null, optional)
    • If omitted or null, the worker defaults to 465 when smtpConfig.secure=true, otherwise 25.
  • status (string, optional)
    • Allowed: active, maintenance, disabled, paused, inactive
  • checkInterval (number, optional)
  • timeoutSeconds (number, optional)
  • checkMode (string, optional)
    • Allowed: protocol, tcp. Defaults to protocol.
    • In tcp mode the monitor performs a bare TCP port-reachability check: smtpConfig is not required and is not stored. In protocol mode the full SMTP protocol/auth check runs (existing behavior).
  • smtpConfig (object, optional)
    • Stored as the monitor's config JSON.

smtpConfig (worker-supported keys)

The SMTP worker coerces/uses these keys:

  • secure (boolean, default false)
  • ignoreTls (boolean, default false)
  • requireTls (boolean, default false)
  • auth.user and auth.pass (strings)
    • Credentials are only used when both user and pass are provided.

Duplicates

If this customer already has a monitor with the same hostname (case and a trailing dot do not count), port and checkMode, the request is refused with 409 and data.code monitorAlreadyExists. data.existingId and data.existingPublicId name the existing monitor. Send "allowDuplicate": true to create the second monitor anyway (for example with a different interval or other alert channels).

  • allowDuplicate (boolean, optional, default false): create the monitor even if it is a duplicate. Not stored.
{
  "statusCode": 409,
  "statusMessage": "A monitor for this target already exists for this customer. Send allowDuplicate: true to create it anyway.",
  "data": { "code": "monitorAlreadyExists", "existingId": 300, "existingPublicId": "44444444-4444-4444-8444-444444444444" }
}

Limit per target host

An organization can have at most 100 monitors for the same target host, counted across all monitor types together (websites with HTTP, keyword, DNS website and Playwright with a real URL, plus TCP, ICMP, DNS, SSH, SMTP, FTP and IMAP/POP). The limit protects against the check fleet being misused as a load generator against third-party hosts. The exact hostname is compared: case, port, path and a trailing dot do not count, but www.example.com and example.com are different hosts. Once the limit is reached, the request is refused with 403 and data.code targetHostMonitorLimitReached. data.host names the normalized host, data.limit the limit. "allowDuplicate": true does not lift the limit. The same check runs when a PATCH changes the hostname. A PATCH that keeps the host always succeeds, and existing monitors above the limit stay in place. If you need a higher limit, contact support. Independently of your organization, at most 300 monitors across all Uptimeify customers may target the same host. Beyond that, the request is refused with 403 and data.code targetHostPlatformLimitReached; data.host and data.limit are set as above, and the message does not reveal how many monitors other organizations have.

{
  "statusCode": 403,
  "statusMessage": "Target host monitor limit reached: your organization already has 100 monitors for example.com (maximum 100 per host). Remove monitors for this host or contact support to raise the limit.",
  "data": { "code": "targetHostMonitorLimitReached", "host": "example.com", "limit": 100 }
}

cURL

curl -X POST "https://YOUR_DOMAIN/api/smtp-monitors" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "customerId": "11111111-1111-4111-8111-111111111111",
    "name": "Outbound SMTP",
    "hostname": "smtp.deinkunde.com",
    "port": 587,
    "status": "active",
    "checkInterval": 60,
    "timeoutSeconds": 30,
    "smtpConfig": {
      "secure": false,
      "ignoreTls": false,
      "requireTls": false,
      "auth": { "user": "username", "pass": "password" }
    }
  }'

Response

{
  "id": 200,
  "organizationId": 1,
  "customerId": 10,
  "name": "Outbound SMTP",
  "hostname": "smtp.deinkunde.com",
  "port": 587,
  "status": "active",
  "checkInterval": 60,
  "timeoutSeconds": 30,
  "allowedCheckCountryCodes": ["DE"],
  "notificationEmail": null,
  "notificationPhoneNumber": null,
  "lastCheckedAt": null,
  "createdAt": "2026-01-01T12:00:00.000Z",
  "updatedAt": "2026-01-01T12:00:00.000Z",
  "config": {
    "secure": false,
    "ignoreTls": false,
    "requireTls": false,
    "auth": { "user": "username", "pass": "password" }
  },
  "smtpConfig": {
    "secure": false,
    "ignoreTls": false,
    "requireTls": false,
    "auth": { "user": "username", "pass": "password" }
  }
}

Errors

  • 400 Invalid hostname or invalid request body
  • 400 Invalid Customer identifier
  • 401 Unauthorized
  • 403 Forbidden (e.g. readonly or global supporter)
  • 403 targetHostMonitorLimitReached: the organization already has 100 monitors for this target host (see Limit per target host); allowDuplicate: true does not lift the limit
  • 403 targetHostPlatformLimitReached: the host already has 300 monitors across all Uptimeify customers (see Limit per target host)
  • 409 monitorAlreadyExists: this customer already has such a monitor (see Duplicates); allowDuplicate: true creates it anyway

On this page