Skip to Content
Uptimeify Docs
MonitorsImap pop monitors

Create IMAP/POP Monitor

Creates a new IMAP/POP monitor.

POST /api/imap-pop-monitors

Authentication

Requires a valid session.

  • Header: Authorization: Bearer <token>

Request Body

{
  "customerId": "11111111-1111-4111-8111-111111111111",
  "name": "Mailbox Access",
  "hostname": "mail.deinkunde.com",
  "port": 993,
  "status": "active",
  "checkInterval": 30,
  "timeoutSeconds": 30,
  "imapPopConfig": {
    "protocol": "imap",
    "user": "monitor@deinkunde.com",
    "password": "password",
    "tls": true,
    "tlsOptions": { "rejectUnauthorized": true }
  }
}

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 /imap).
  • port (number | null, optional)
    • If omitted or null, the worker chooses a default port depending on imapPopConfig.protocol and imapPopConfig.tls.
  • status (string, optional)
    • Allowed: active, maintenance, disabled, paused, inactive
    • Note: paused / inactive are normalized to disabled.
  • 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: imapPopConfig is not required and is not stored. In protocol mode the full IMAP/POP login check runs (existing behavior).
    • port is required when checkMode is tcp. Without it the request fails with 400 / data.code: "portRequiredForTcp".
  • imapPopConfig (object, optional)
    • Stored as the monitor's config JSON.
    • Required (user + password) unless checkMode is tcp.

imapPopConfig (worker-supported keys)

  • protocol (imap | pop3)
    • Default: imap
  • user (string)
  • password (string)
  • tls (boolean)
    • Default: false
  • tlsOptions.rejectUnauthorized (boolean)
    • Used by the IMAP worker library; POP3 currently ignores this option.

Default ports (worker behavior)

If port is omitted or null:

  • IMAP:
    • TLS (tls: true): 993
    • Non-TLS (tls: false): 143
  • POP3:
    • TLS (tls: true): 995
    • Non-TLS (tls: false): 110

Duplicates

If this customer already has a monitor with the same hostname (case and a trailing dot do not count), port, checkMode and imapPopConfig.protocol, 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/imap-pop-monitors" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "customerId": "11111111-1111-4111-8111-111111111111",
    "name": "Mailbox Access",
    "hostname": "mail.deinkunde.com",
    "port": 993,
    "status": "active",
    "checkInterval": 30,
    "timeoutSeconds": 30,
    "imapPopConfig": { "protocol": "imap", "user": "monitor@deinkunde.com", "password": "password", "tls": true }
  }'

Response

{
  "id": 500,
  "organizationId": 1,
  "customerId": 10,
  "name": "Mailbox Access",
  "hostname": "mail.deinkunde.com",
  "port": 993,
  "checkInterval": 30,
  "timeoutSeconds": 30,
  "allowedCheckCountryCodes": ["DE"],
  "status": "active",
  "notificationPhoneNumber": null,
  "notificationEmail": null,
  "lastCheckedAt": null,
  "createdAt": "2026-02-26T12:00:00.000Z",
  "updatedAt": "2026-02-26T12:00:00.000Z",
  "config": {
    "protocol": "imap",
    "user": "monitor@deinkunde.com",
    "password": "password",
    "tls": true
  },
  "imapPopConfig": {
    "protocol": "imap",
    "user": "monitor@deinkunde.com",
    "password": "password",
    "tls": true
  }
}

Errors

  • 400 Invalid hostname or invalid request body
  • 400 Invalid Customer identifier
  • 401 Unauthorized
  • 403 Forbidden (e.g. readonly or global supporter)
  • 404 Customer not found
  • 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