# See the mailbox servers

`GET https://api.mailmasker.org/api/v1/admin/dovecot/status`

Which mailbox server is active, which are standing by, and whether each is up.

- Who can use it: Site admins
- Area: Fleet and status
- Answers 200 OK when it works
- Page: https://developer.mailmasker.org/admin-dovecot-status

One mailbox server is active and does all the mail work: reading mail, delivering it, and checking passwords for sending. The others stand by, and if the active one goes down all of that moves to a standby together. `paths` lists those mail services and their ports, and `note` explains the arrangement.

## Good to know

- `healthy` means the server's agent checked in within the last 3 minutes; it doesn't test the mail service itself.
- `role` is the planned layout from the api's own settings, not a live reading: if the mail service fails over by itself, this still names the old server as active.
- `last_heartbeat` is null for a server whose agent has never checked in.

## Examples

cURL:

```bash
curl -s 'https://api.mailmasker.org/api/v1/admin/dovecot/status' \
  -H "Authorization: Bearer $TOKEN"
```

Perl:

```perl
use Mojo::Base -strict;
use Mojo::UserAgent;

my $ua  = Mojo::UserAgent->new;
my $res = $ua->get('https://api.mailmasker.org/api/v1/admin/dovecot/status',
    { Authorization => "Bearer $ENV{TOKEN}" })->result;
die $res->code, ' ', ($res->json('/error') // $res->message), "\n" unless $res->is_success;
print $res->body, "\n";
```

homelab-cli:

```bash
homelab-cli admin dovecot status
```

## Response

200 OK:

```json
{
  "active_address": "192.0.2.62",
  "hosts": [
    {
      "name": "prod-homelabvm62",
      "address": "192.0.2.62",
      "role": "active",
      "healthy": true,
      "last_heartbeat": "2026-11-03 21:42:10.123456-06"
    },
    {
      "name": "prod-homelabvm63",
      "address": "192.0.2.63",
      "role": "standby",
      "healthy": true,
      "last_heartbeat": "2026-11-03 21:41:58.907311-06"
    }
  ],
  "paths": [
    { "name": "IMAP / IMAPS", "ports": "143, 993", "via": "HAProxy active/passive" },
    { "name": "LMTP delivery", "ports": "24", "via": "HAProxy active/passive" },
    { "name": "SASL submission auth", "ports": "12345", "via": "HAProxy active/passive" }
  ],
  "note": "Active/passive: exactly one host (the active one) serves ALL mail -- IMAP/IMAPS reads, LMTP delivery, and SASL submission auth -- so its local maildir index stays authoritative (shared storage, per-host indexes). All three paths fail over together to a standby if the active host goes down. Enforced by homelab-haproxy active_passive; keep the pool here in sync with its backends.yml."
}
```