# Elektromail Product Documentation
## Overview
Elektromail is a minimal IMAP/SMTP mail server for local development, demos, and end-to-end testing. It provides real protocol interactions with deterministic behavior, low resource usage, and a simple configuration model. It is not intended for production mail hosting.
Default ports are IMAP `1143` and SMTP `2525`.
## Quick Start
Use the README for installation and Docker examples. A minimal local run looks like this:
```bash
cargo run
```
Optional credentials:
```bash
ELEKTROMAIL_USERS=demo:demo cargo run
```
## Protocol Support
### IMAP
Elektromail implements IMAP4rev2 (RFC 9051) with IMAP4rev1 compatibility.
Supported commands:
- CAPABILITY
- NOOP
- LOGOUT
- LOGIN
- AUTHENTICATE PLAIN
- STARTTLS
- LIST
- LSUB
- SELECT
- EXAMINE
- CREATE
- DELETE
- RENAME
- SUBSCRIBE
- UNSUBSCRIBE
- FETCH
- UID FETCH
- STORE
- UID STORE
- SEARCH
- UID SEARCH
- COPY
- UID COPY
- MOVE
- UID MOVE
- APPEND
- EXPUNGE
- UID EXPUNGE
- IDLE
- STATUS
- NAMESPACE
- CLOSE
- UNSELECT
- GETQUOTA
- GETQUOTAROOT
FETCH items:
- RFC822
- RFC822.SIZE
- RFC822.HEADER
- FLAGS
- UID
- INTERNALDATE
- ENVELOPE
- BODYSTRUCTURE
- BODY[]
- BODY.PEEK[]
SEARCH criteria:
- ALL
- SINCE, BEFORE, ON
- SENTSINCE, SENTBEFORE
- SEEN, UNSEEN, FLAGGED, DELETED, ANSWERED, DRAFT
- LARGER, SMALLER
- SUBJECT, FROM, TO
- TEXT
- HEADER name value
- NOT, OR
IMAP extensions and capabilities:
- IMAP4rev2 and IMAP4rev1
- UIDPLUS (APPENDUID, COPYUID)
- LITERAL+ (non-synchronizing literals)
- IDLE
- MOVE
- AUTH=PLAIN
- STARTTLS
- QUOTA (minimal responses for GETQUOTA/GETQUOTAROOT)
Notes:
- SEARCH dates use `DD-Mon-YYYY`.
- INTERNALDATE format is `DD-Mon-YYYY HH:MM:SS +ZZZZ`.
- UIDVALIDITY is fixed to `1` and UIDNEXT is sequential per mailbox.
### SMTP
Elektromail implements ESMTP (RFC 5321) with SMTP Submission behavior (RFC 6409).
Supported commands:
- EHLO / HELO
- MAIL FROM
- RCPT TO
- DATA
- RSET
- NOOP
- QUIT
- AUTH PLAIN
- STARTTLS
Extensions:
- SIZE
Plus-addressing is supported: `user+tag@domain` is delivered to `user`.
Mailboxes are created on first delivery if they do not already exist.
## Configuration
Environment variables:
| ELEKTROMAIL_USERS | user:pass | Comma-separated credentials |
| ELEKTROMAIL_AUTH_DISABLED | - | Accept any credentials if set to true/1/yes |
| ELEKTROMAIL_DB | - | SQLite database path for persistence |
| SMTP_PORT | 2525 | SMTP listen port |
| IMAP_PORT | 1143 | IMAP listen port |
| HTTP_PORT | - | HTTP control plane port (disabled if unset) |
| BIND_ADDR | 0.0.0.0 | Bind address |
User provisioning formats:
- `user:pass`
- `user:user@example.com:pass`
- Multiple users separated by commas
## Storage
- In-memory storage is the default and is cleared on shutdown.
- SQLite persistence is enabled by setting `ELEKTROMAIL_DB`.
## HTTP Control Plane
Enable with `HTTP_PORT`. Endpoints:
| /reset | POST | Clear all mailboxes |
| /inject | POST | Inject email directly (JSON body) |
| /users | GET | List configured users |
| /messages | GET | List all messages |
| /messages?user=X&mailbox=Y | GET | List messages for a mailbox |
## Modes of Operation
- Test mode: loopback by default, in-memory storage, fast reset.
- Dev/demo mode: optional TLS, optional persistence, more verbose logs.
## Determinism and Testing
- UID allocation is deterministic and sequential per mailbox.
- The RFC 9051 compliance harness lives in `tests/rfc9051/`.
## Non-Goals
- Production-grade mail hosting
- POP3 support
- Advanced IMAP extensions beyond the listed set
- DKIM/DMARC/SPF, spam filtering, or outbound relay validation