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).
- Must be a hostname only (no protocol like
port(number | null, optional)- If omitted or
null, the worker chooses a default port depending onimapPopConfig.protocolandimapPopConfig.tls.
- If omitted or
status(string, optional)- Allowed:
active,maintenance,disabled,paused,inactive - Note:
paused/inactiveare normalized todisabled.
- Allowed:
checkInterval(number, optional)timeoutSeconds(number, optional)checkMode(string, optional)- Allowed:
protocol,tcp. Defaults toprotocol. - In
tcpmode the monitor performs a bare TCP port-reachability check:imapPopConfigis not required and is not stored. Inprotocolmode the full IMAP/POP login check runs (existing behavior). portis required whencheckModeistcp. Without it the request fails with400/data.code: "portRequiredForTcp".
- Allowed:
imapPopConfig(object, optional)- Stored as the monitor's
configJSON. - Required (
user+password) unlesscheckModeistcp.
- Stored as the monitor's
imapPopConfig (worker-supported keys)
protocol(imap|pop3)- Default:
imap
- Default:
user(string)password(string)tls(boolean)- Default:
false
- Default:
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
- TLS (
- POP3:
- TLS (
tls: true):995 - Non-TLS (
tls: false):110
- TLS (
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, defaultfalse): 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
400Invalid hostname or invalid request body400Invalid Customer identifier401Unauthorized403Forbidden (e.g.readonlyor global supporter)404Customer not found403targetHostMonitorLimitReached: the organization already has 100 monitors for this target host (see Limit per target host);allowDuplicate: truedoes not lift the limit403targetHostPlatformLimitReached: the host already has 300 monitors across all Uptimeify customers (see Limit per target host)409monitorAlreadyExists: this customer already has such a monitor (see Duplicates);allowDuplicate: truecreates it anyway