warmbly/resources/imap.md

IMAP Integration

Warmbly supports IMAP/SMTP for non-Gmail email providers, including Outlook (with OAuth2) and standard IMAP servers.

Overview

IMAP (Internet Message Access Protocol) is used for reading emails from mailboxes. Combined with SMTP for sending, it provides full email functionality for providers that don't offer a REST API.

CondStore Extension

CondStore (RFC 7162) enables efficient incremental synchronization using modification sequences (MODSEQ).

How It Works

1. Server assigns a MODSEQ to each message modification
2. Client stores the highest MODSEQ seen
3. On next sync, client requests only changes since that MODSEQ
4. Reduces bandwidth and processing compared to full sync

IMAP Commands

# Check for CondStore support
A1 SELECT INBOX
* OK [HIGHESTMODSEQ 123456]

# Fetch changes since last sync
A2 FETCH 1:* (FLAGS) (CHANGEDSINCE 123456)

Authentication

Plain Authentication

Standard username/password authentication for most IMAP servers.

Hostname: imap.example.com
Port: 993 (SSL) or 143 (STARTTLS)
Username: user@example.com
Password: app-specific-password

OAuth2 (XOAUTH2)

Used for Microsoft Outlook and other OAuth2-supporting providers.

# XOAUTH2 SASL mechanism
AUTH XOAUTH2 <base64-encoded-token>

The token format:

user=email@example.com^Aauth=Bearer <access_token>^A^A

SMTP Sending

Outgoing emails are sent via SMTP, typically on port 587 with STARTTLS.

Hostname: smtp.example.com
Port: 587 (STARTTLS) or 465 (SSL)

Folder Management

UIDValidity

IMAP uses UIDValidity to detect mailbox changes. If UIDValidity changes, all cached UIDs are invalid and a full resync is required.

Common Folders

Folder	IMAP Name	Description
Inbox	INBOX	Primary inbox
Sent	Sent, Sent Items, Sent Mail	Sent messages
Drafts	Drafts	Draft messages
Trash	Trash, Deleted Items	Deleted messages
Spam	Spam, Junk	Spam folder

Supported Providers

Provider	IMAP Server	SMTP Server	Auth
Outlook	outlook.office365.com:993	smtp.office365.com:587	OAuth2
Yahoo	imap.mail.yahoo.com:993	smtp.mail.yahoo.com:587	App Password
Zoho	imap.zoho.com:993	smtp.zoho.com:587	App Password
Custom	configurable	configurable	Plain

Error Handling

Error	Cause	Resolution
LOGIN failed	Invalid credentials	Refresh token or update password
UIDVALIDITY changed	Mailbox reset	Full resync required
Connection timeout	Network issue	Retry with backoff
Too many connections	Rate limit	Queue and retry

Code References

• IMAP client: internal/email/imap.go
• OAuth2 SASL: Uses github.com/emersion/go-sasl
• IMAP library: github.com/emersion/go-imap/v2