mirror of
https://github.com/warmbly/warmbly.git
synced 2026-08-19 00:01:14 +00:00
Máté Mészáros (Laptop)
106 lines
2.8 KiB
Markdown
106 lines
2.8 KiB
Markdown
# 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`
|