Getting started: IMAP access

This walkthrough shows how to enable IMAP access on an Everlock instance that already receives inbound mail via SMTP. By the end you'll be able to connect Thunderbird, Apple Mail, K-9 Mail, or any standard IMAP client to your mailbox.

Prerequisites

• Everlock running with backend-mail-smtp enabled and at least one mail domain configured. See Getting started: Inbound mail if you haven't done this yet.
• Port 993 (IMAPS) reachable from your mail clients — open a firewall / NAT rule if needed.

1. Set a user password

IMAP authentication uses the same Password credential stored in the user registry. If you haven't already set a password for the user, SSH into the admin shell and run:

/users password alice@example.com

You'll be prompted to enter and confirm a password. The username on the IMAP wire is the full email address — the local part before @ is also the on-disk mailbox name.

2. Enable the IMAP backend

The IMAP backend reads from the same versioned store as the SMTP backend. Enable it with the flag or environment variable:

everlock serve \
  --frontend-smtp --backend-mail-smtp \
  --backend-mail-imap

or:

EVERLOCK_BACKEND_MAIL_IMAP=true

The backend uses the same store as SMTP (everlock-mail by default). No data migration is needed — mail already delivered by SMTP is immediately visible once the backend is up.

3. Enable the IMAP frontend

The IMAP frontend handles the wire protocol on port 993 (IMAPS):

everlock serve \
  --frontend-smtp --backend-mail-smtp \
  --backend-mail-imap \
  --frontend-imap --frontend-imap-tls-listen 0.0.0.0:993

or:

EVERLOCK_FRONTEND_IMAP=true
EVERLOCK_FRONTEND_IMAP_TLS_LISTEN=0.0.0.0:993

Optional STARTTLS on port 143, mainly for legacy clients on local networks:

EVERLOCK_FRONTEND_IMAP_STARTTLS_LISTEN=0.0.0.0:143

TLS certificates are shared with the SMTP frontend — Everlock reads the same config/mail.<domain>/fullchain.pem and privkey.pem that SMTP writes via ACME. No separate certificate provisioning needed.

4. Verify DNS records

If Everlock manages the DNS zone for your domain, run:

/mail domains list example.com

You should see confirmed active records including:

DNS: derived MX records for 'example.com' are active.
DNS: derived SRV record for IMAPS autoconfiguration is active at '_imaps._tcp.example.com'.
DNS: derived SRV record for submission autoconfiguration is active at '_submission._tcp.example.com'.

These SRV records (RFC 6186 / RFC 2782) let Thunderbird, Apple Mail, and K-9 Mail discover the correct server, port, and security settings from just the user's email address — no manual hostname entry.

If the SRV records aren't listed, force a DNS reload:

/dns reload

If you're using an external DNS provider, add these records manually:

Name	Type	Value
_imaps._tcp.example.com	SRV	0 1 993 mail.example.com.
_submission._tcp.example.com	SRV	0 1 587 mail.example.com.

5. Connect a mail client

Thunderbird

1. Open File → New → Existing Mail Account.
2. Enter your full email address (alice@example.com) and password.
3. Click Configure Automatically — Thunderbird discovers IMAPS via the SRV record.
4. Confirm the detected settings:
   • Incoming: IMAP · mail.example.com · port 993 · SSL/TLS
   • Outgoing: SMTP · mail.example.com · port 587 · STARTTLS
5. Click Done.

If autoconfiguration doesn't trigger, click Manual configuration and fill in the values above directly.

Apple Mail (macOS / iOS)

1. System Settings → Internet Accounts → Add Account → Other Mail Account.
2. Enter your name, email address, and password.
3. With SRV records in place, Mail prefills the server details. Otherwise:
   • Incoming Mail Server: mail.example.com, port 993, SSL
   • Outgoing Mail Server: mail.example.com, port 587, STARTTLS

K-9 Mail (Android)

1. Settings → Add Account, enter your email address, tap Manual setup.
2. Choose IMAP.
3. Incoming: mail.example.com, port 993, SSL/TLS, username alice@example.com.
4. Outgoing: mail.example.com, port 587, STARTTLS, same username and password.

6. Verify end-to-end

1. Send an inbound test message via SMTP.
2. Open your mail client — the message should appear in INBOX within seconds via IMAP IDLE push notification.
3. Mark it as read on one device; open another client — the \Seen flag should sync within ~1 second.
4. Save a draft in Thunderbird — it should appear under drafts in Apple Mail immediately.
5. Move a message to Trash — it should disappear from INBOX and appear in Trash on all connected clients.

Folder layout

Everlock exposes five standard folders to all IMAP clients. Modern clients identify them by their SPECIAL-USE attribute (RFC 6154), not by name matching, so the lowercase display names work correctly in all tested clients.

IMAP name	Special-use attribute
INBOX	(none)
sent	\Sent
drafts	\Drafts
trash	\Trash
junk	\Junk

Custom folder names created by rules.toml actions (e.g. alerts) are SELECT-able by name but don't show up in LIST.

Troubleshooting

Client can't connect on port 993 — check that --frontend-imap-tls-listen is set and the port is open in your firewall. Run ss -tlnp | grep 993 on the host to confirm Everlock is listening.

Certificate error / untrusted — before ACME issues a managed certificate, Everlock serves a self-signed cert. Accept the exception once, or wait for ACME to complete and restart Everlock to pick up the new cert.

Login fails with AUTHENTICATIONFAILED — verify the password with /users password alice@example.com (re-set it if needed). Everlock requires the full user@domain as the IMAP username.

No messages visible — IMAP folders are virtual; they show all messages whose sidecar folder field matches. Confirm at least one message exists with /mail mailboxes list example.com alice.

SRV records not detected by client — flush the client's DNS cache, or verify the SRV records are published with:

dig SRV _imaps._tcp.example.com

This should return the record pointing to mail.example.com:993.

Read next

• Mail backend reference
• Getting started: Inbound mail
• Getting started: Outbound mail
• Frontends