@smbcloud / smbcloud-mail-imap
Code Commits Issues Pulls Cloud Agent CI/CD
copilot/add-pop3-protocol-examples
copilot/add-pop3-protocol-examples copilot/add-pop3-protocol-implementation copilot/implement-mail-handling-separation development main
md 163 lines 3.9 KB
Rendered Raw
1 # Mail Server
2
3 A mail server implementation in Rust with support for SMTP, POP3, and IMAP protocols with TLS/STARTTLS support.
4
5 ## Features
6
7 - ✅ Basic SMTP protocol support (HELO/EHLO, MAIL FROM, RCPT TO, DATA, QUIT)
8 - ✅ STARTTLS support for secure connections
9 - ✅ Self-signed certificate generation for TLS
10 - ✅ Async/await with Tokio runtime
11 - ✅ Structured logging with tracing
12 - ✅ Multiple recipient support
13 - ✅ Command validation and error handling
14
15 ## Running the Server
16
17 ```bash
18 cargo run
19 ```
20
21 The server listens on `127.0.0.1:2525` by default.
22
23 ## Testing
24
25 You can test the server using `nc` (netcat) or `telnet`:
26
27 ```bash
28 echo -e "EHLO test.com\r\nMAIL FROM: <sender@example.com>\r\nRCPT TO: <recipient@example.com>\r\nDATA\r\nSubject: Test\r\n\r\nTest message\r\n.\r\nQUIT\r\n" | nc localhost 2525
29 ```
30
31 ## Supported Commands
32
33 - `HELO/EHLO` - Initiate SMTP session
34 - `MAIL FROM` - Specify sender email address
35 - `RCPT TO` - Specify recipient email address (supports multiple)
36 - `DATA` - Begin email message content
37 - `RSET` - Reset the current transaction
38 - `NOOP` - No operation (keepalive)
39 - `QUIT` - Close connection
40 - `STARTTLS` - Upgrade connection to TLS
41
42 ## Building
43
44 ```bash
45 cargo build --release
46 ```
47
48 ## POP3 Protocol Support
49
50 This repository includes comprehensive examples and documentation for the POP3 (Post Office Protocol version 3) implementation.
51
52 ### POP3 Features
53
54 - ✅ USER/PASS authentication
55 - ✅ STAT command for mailbox statistics
56 - ✅ LIST command for message listing
57 - ✅ RETR command for message retrieval
58 - ✅ DELE command for message deletion
59 - ✅ RSET command to unmark deletions
60 - ✅ NOOP keepalive command
61 - ✅ Optional TLS/SSL support (POP3S)
62
63 ### POP3 Examples
64
65 The repository includes comprehensive POP3 examples:
66
67 #### Rust Examples
68
69 ```bash
70 # Run the POP3 client example
71 cargo run --example pop3_client
72
73 # Run the POP3 server example
74 cargo run --example pop3_server
75
76 # Run integration tests
77 cargo run --example pop3_integration_test
78 ```
79
80 #### Python Example
81
82 ```bash
83 # Run the Python POP3 client
84 python3 docs/scripts/pop3-client.py
85 ```
86
87 #### Manual Testing with netcat
88
89 ```bash
90 # Connect to POP3 server
91 nc localhost 110
92
93 # Then type commands:
94 USER testuser
95 PASS testpass
96 STAT
97 LIST
98 RETR 1
99 QUIT
100 ```
101
102 ### POP3 Documentation
103
104 For comprehensive POP3 documentation, see [docs/POP3.md](docs/POP3.md), which includes:
105
106 - Protocol basics and command reference
107 - Setup and configuration guide
108 - Usage examples for clients and servers
109 - Unit and integration testing examples
110 - Integration with SMTP and IMAP
111 - Troubleshooting guide
112 - Best practices for security and performance
113
114 ### POP3 Quick Start
115
116 ```rust
117 // Example: Connect to POP3 server and retrieve messages
118 use std::io::{BufRead, BufReader, Write};
119 use std::net::TcpStream;
120
121 fn main() -> Result<(), Box<dyn std::error::Error>> {
122 let mut stream = TcpStream::connect("localhost:110")?;
123 let mut reader = BufReader::new(stream.try_clone()?);
124
125 // Read greeting
126 let mut greeting = String::new();
127 reader.read_line(&mut greeting)?;
128 println!("{}", greeting);
129
130 // Authenticate
131 writeln!(stream, "USER testuser")?;
132 let mut response = String::new();
133 reader.read_line(&mut response)?;
134
135 writeln!(stream, "PASS testpass")?;
136 response.clear();
137 reader.read_line(&mut response)?;
138
139 // Get mailbox statistics
140 writeln!(stream, "STAT")?;
141 response.clear();
142 reader.read_line(&mut response)?;
143 println!("{}", response);
144
145 // Close connection
146 writeln!(stream, "QUIT")?;
147
148 Ok(())
149 }
150 ```
151
152 See [examples/pop3_client.rs](examples/pop3_client.rs) for a complete client implementation with all POP3 commands.
153
154 ## Dependencies
155
156 - `tokio` - Async runtime
157 - `anyhow` - Error handling
158 - `tracing` / `tracing-subscriber` - Logging
159 - `regex` - SMTP command parsing
160 - `native-tls` / `tokio-native-tls` - TLS support
161 - `openssl` - Certificate generation
162 - `futures` - Stream handling
163 - `tokio-util` - Codec utilities