---
title: IMAP monitoring: mailbox login, TLS and new mail with WatchFor
description: Monitor an IMAP server the way a mail client meets it — TLS and certificate, capabilities, login, mailbox and folder counts, the age of the newest message, how full the mailbox is (quota) — with a mail server grade from A+ to F.
canonical: https://watchfor.io/docs/monitors/imap
---

# IMAP monitoring: mailbox login, TLS and new mail with WatchFor

Monitor an IMAP server the way a mail client meets it — TLS and certificate, capabilities, login, mailbox and folder counts, the age of the newest message, how full the mailbox is (quota) — with a mail server grade from A+ to F.

A mail server can accept connections and still be broken for the people who
read mail on it: the certificate expired overnight, a password change locked
out the shared support inbox, the mailbox that receives your nightly
backup report has not seen a new message in three days, or the mailbox
quietly filled up and every new message now bounces. An **IMAP monitor**
connects the way a mail client does and tells you which of those happened.

Each check connects, negotiates TLS, reads the greeting and the server's
capabilities and, when you give it a login, signs in, lists the folders, opens
the mailbox read-only, reads the date of the newest message and asks how full
the mailbox is (its quota). Only counts, dates and sizes are kept. No subject, sender or message body is read or
stored, and nothing is marked as read.

**Target:** the IMAP server's host name, for example `imap.example.com` or
`imap.gmail.com`.

IMAP monitors are on the **Pro** and **Business** plans, like SMTP, FTP and
SFTP. For POP3 servers, see [POP3](/docs/monitors/pop3). To test that mail
actually travels from your sending server into a mailbox, see
[Email round-trip](/docs/monitors/email-round-trip).

## Settings

| Setting | Notes |
| --- | --- |
| **Encryption** | **Implicit TLS** (port 993, encrypted from the first byte, the safest choice), **STARTTLS** (port 143, connects in plain text and upgrades; the check fails if the server stops offering the upgrade) or **None** (port 143, greeting and capabilities only). |
| **Port** | Follows the encryption mode (993 or 143) unless you type a custom port. |
| **Verify certificate** | On by default: an expired, self-signed or mismatched certificate fails the check. Off still reports the certificate, it just stops failing on it. |
| **Username** | Optional. Empty means a connection-only check: greeting, TLS and capabilities. |
| **Password** | Required with a username. Stored encrypted and never shown again (see [Credentials](#credentials)). |
| **Mailbox** | Shown with a username. The folder to open, `INBOX` by default. Opened read-only (`EXAMINE`), so nothing is marked as read. |
| **Track newest message age** | On by default. Reads the arrival date of the newest message so you can alert when mail stops coming in. Only the date is read. |
| **List folders** | On by default. Counts the folders and notes the special ones (Sent, Junk, Trash). |
| **Timeout** and **IP version** | Seconds per connection (default 15, at most 60); Auto / IPv4 / IPv6. |

A login always needs Implicit TLS or STARTTLS. With **None**, the monitor
never sends credentials; it checks the greeting and capabilities and reports
whether the server would accept a password on that unencrypted connection.

### Gmail, Microsoft 365 and other providers

- **Gmail and Google Workspace** need an
  [app password](https://support.google.com/accounts/answer/185833), which
  requires 2-Step Verification on the account. Your normal Google password
  is refused.
- **Microsoft 365 and Outlook.com** have turned off password (basic) logins
  for IMAP and POP3. WatchFor does not support OAuth sign-in yet, so a login
  check against a Microsoft 365 mailbox fails. A connection-only check (no
  username) still works and still grades TLS and the certificate.
- **Your own server** (Dovecot, Courier, Exchange on-premises, a hosting
  provider's mail): use a dedicated monitoring account with access to one
  mailbox rather than a person's login.

## What each check measures

| Stage | What it tells you |
| --- | --- |
| **DNS, connect** | Resolve time and TCP connect time to the port. |
| **TLS** | Handshake time, negotiated TLS version and cipher, the certificate's subject, issuer, expiry and whether it verifies. |
| **Greeting, capabilities** | How fast the server says hello, and what it offers after TLS (`IDLE`, authentication methods). In STARTTLS and None mode also whether `STARTTLS` is offered and whether a password login is offered before encryption. |
| **Login** | Whether the username and password are accepted, how long it takes, and the kind of failure when it is not (wrong password, account disabled, TLS required). |
| **Folders** | How many folders exist and which have special-use flags (Sent, Junk, Trash, Drafts). |
| **Mailbox** | Messages and unseen messages in the mailbox you chose. |
| **Newest message** | The arrival date and size of the newest message, and how many seconds ago that was. An empty mailbox reports no age. |
| **Mailbox space** | How full the mailbox is: used space of the quota limit (for example 37.2 MB of 100 MB) and, if the server counts them, messages of the message limit. See [Mailbox quota](#mailbox-quota). |

Every stage's duration is stored, so a slow check shows where the time went.

### Mailbox quota

A full mailbox does not announce itself: the server simply starts rejecting
new mail, and the senders get the bounce, not you. After the login, when the
server supports the IMAP **QUOTA** extension (RFC 9208: Dovecot, Cyrus and
most hosting providers do), the check asks for the quota of the monitored
mailbox. That command only reads; nothing in the mailbox changes.

- **Used and limit.** The storage quota (used space of the limit) and, when
  the server has one, the message-count quota. The higher of the two
  percentages is what the alert compares, so a mailbox that runs out of
  message slots first still warns in time.
- **Several quotas.** A mailbox can sit under more than one quota (for
  example a user quota and a domain quota). The tightest one is shown.
- **Unlimited.** A quota without a limit shows as *Unlimited*; there is no
  percentage to alert on.
- **No quota support.** If the server reports no quota but can tell the
  mailbox size (`STATUS=SIZE`), the size is shown without a limit, and the
  **Mailbox Size** preset can alert on it. If it reports neither, the card
  says so and the space alerts stay quiet.
- **Gmail** does not report a quota over IMAP, and Microsoft 365 logins
  need OAuth (see above), so mailbox space is measured on servers like
  Dovecot and most hosting providers' mail.

The monitor page shows this first, right after Uptime and Incidents, as a
thin bar that stays grey until the mailbox is close to full: amber from
90 %, red from 99 %. A quota answer that can't be read never fails the check
and never changes the mail server grade.

### Mail server grade

The monitor page grades the server from **A+** to **F** from the latest check,
with the reasons listed under the letter. It starts at A+ and each finding
caps it:

| Finding | Grade at most |
| --- | --- |
| No encryption (Encryption: None), failed TLS handshake, or a certificate that is expired or not trusted | F |
| TLS 1.0 or 1.1 negotiated | C |
| A password login offered before encryption | C |
| Certificate expires within 7 days | C |
| Certificate expires within 14 days | B |
| Login rejected | B |
| The whole check took longer than 5 seconds | B |
| STARTTLS instead of implicit TLS | A |
| TLS 1.2 rather than 1.3 | A |

A check that never reached the server (DNS failure, connection refused, a
timeout before TLS) gets no grade, so a network problem is not blamed on
the server.

## Alert presets

| Preset | Default | Fires when |
| --- | --- | --- |
| **Probe Status** | on (locked, critical) | The server can't be reached, TLS fails, or (with a login) the login or opening the mailbox fails. |
| **Login Failed** | on when a username is set (critical) | The server refuses the monitor's login. |
| **Certificate Expiry** | on (warning) | The certificate has fewer than 14 days left. Nothing to measure with Encryption: None. |
| **Certificate Not Trusted** | off | The certificate does not verify (expired, self-signed, wrong host name, incomplete chain). With **Verify certificate** on, such a certificate already fails the check; this preset is for monitors that skip verification. |
| **Plaintext Login Offered** | off | The server offers a password login on an unencrypted connection, before STARTTLS or with TLS off. Measured in STARTTLS and None modes. |
| **STARTTLS Not Offered** | off | The server on the plain port does not offer STARTTLS, so clients there cannot encrypt at all. Measured in STARTTLS and None modes. |
| **Slow Check** | off | The whole check (connect, TLS, greeting, login and mailbox) takes longer than 5000 ms. |
| **No New Mail** | off | The newest message is older than the threshold in seconds (86400 = a day). Needs a login. |
| **Mailbox Almost Full** | on for new monitors with a login (warning at 90 %, critical **Mailbox Full** at 99 %) | The mailbox quota is at least that full. Both levels are adjustable and can be switched off separately. Measured only when the server reports a quota; without one the rule stays quiet. Monitors created before this preset existed are not changed, switch it on in the Alerting tab. |
| **Mailbox Size** | off | The mailbox is larger than the size you set, in MB (500 MB by default). Uses the quota's used space when the server reports a quota, otherwise the mailbox's size (`STATUS=SIZE`). For servers without a quota. Needs a login. |

**No New Mail** is the one to turn on for a mailbox that should receive
something regularly: a nightly backup report, form submissions, invoices
from a supplier. When the newest message gets too old, something upstream
stopped sending. **Mailbox Almost Full** is what stops the opposite
problem: mail that can't arrive because the mailbox is full.

### Metrics for custom rules

All IMAP metrics are in the `imap.` namespace, for example
`metrics['imap.newest_message_age_s'] > 86400`.

| Metric | Meaning |
| --- | --- |
| `imap.error_count` | `1` when the check failed (connection, TLS or login). |
| `imap.auth_ok` | `1` login accepted, `0` refused. Only reported when a username is set. |
| `imap.cert_days_left`, `imap.cert_valid` | Days until the certificate expires; `1` when it verifies. |
| `imap.tls_version` | Negotiated version: `1.0` to `1.3`. |
| `imap.starttls_offered`, `imap.plaintext_login_allowed` | STARTTLS offered on the plain port; a password login offered without encryption (`1` is bad). STARTTLS and None modes only. |
| `imap.idle_supported` | `1` when the server supports `IDLE` (push to clients). |
| `imap.messages`, `imap.unseen`, `imap.folders` | Mailbox counts. |
| `imap.newest_message_age_s` | Seconds since the newest message arrived. |
| `imap.quota_used_pct` | How full the quota is, `0` to `100` (the higher of storage and message count). Only when the server reports a quota with a limit. |
| `imap.quota_used_bytes`, `imap.quota_limit_bytes` | Storage used and the storage limit, in bytes (no limit when unlimited). |
| `imap.mailbox_bytes` | Mailbox size in bytes: the quota's used space, or the mailbox's size when the server has no quota. 1 MB = 1,048,576 bytes. |
| `imap.quota_supported` | `1` when the server reports a quota, `0` when it does not. Only reported with a login. |
| `imap.check_time_ms` | The whole check. |
| `imap.dns_time_ms`, `imap.connect_time_ms`, `imap.tls_time_ms`, `imap.greeting_ms`, `imap.capability_ms`, `imap.auth_ms`, `imap.list_ms`, `imap.select_ms`, `imap.fetch_ms`, `imap.quota_ms` | Per-stage timings. |

## Credentials

A mailbox password usually unlocks more than mail: password resets for
every other account arrive there. WatchFor treats it accordingly.

- It is **encrypted at rest** (AES-256-GCM) and bound to this monitor, so
  the stored value can't be decrypted for any other monitor or organization.
- It is **write-only**. After saving, the form shows that a password is
  saved, never the password. API and MCP responses return it as
  `"[redacted]"`, and it never appears in check results, error messages,
  logs, exports or the activity log.
- When you edit the monitor, leave the field as is to keep the saved
  password or press **Replace** to set a new one. Clearing the username
  deletes the saved password with it.
- A saved password never follows the monitor somewhere else: changing the
  server, port, encryption or username, or turning certificate checks off,
  asks for the password again (the API answers `400` until it is sent).
- It is only ever sent over an encrypted connection. A monitor never logs in
  with Encryption: None, and in STARTTLS mode it refuses to log in when the
  upgrade is not offered.

## Also via API

Create with `type: "imap"` (config: `port`, `tlsMode`, `verifyTls`,
`username`, `password`, `mailbox`, `listFolders`, `checkNewestAge`,
`timeoutSeconds`). See the type catalog for [IMAP](/docs/api/monitor-types#imap).

---

Canonical page: https://watchfor.io/docs/monitors/imap · All docs: https://watchfor.io/docs · Site guide: https://watchfor.io/llms.txt