Skip to content

Commit d92244f

Browse files
ColinCopilot
Colin
and
Copilot
committed
feat: add IMAP STARTTLS support with RFC 8314 security enum
Replace ambiguous use_ssl/start_ssl boolean pair with a clean ConnectionSecurity enum (tls/starttls/none) per RFC 8314. Changes: - Add ConnectionSecurity enum to config.py - Add model_validator for backward compat with use_ssl/start_ssl - Implement IMAP STARTTLS transport upgrade via asyncio.loop.start_tls() - Add _create_imap_connection() factory for TLS/STARTTLS/plaintext - Add IMAP verify_ssl support for self-signed certificates - Wire SMTP flags from security enum in EmailClient - Add MCP_EMAIL_SERVER_IMAP_SECURITY/SMTP_SECURITY env vars - Update existing tests to use _connect_imap instead of imap_class - Add comprehensive tests for new security features - Update README with security modes, env vars, and ProtonMail Bridge example Existing configs with use_ssl/start_ssl continue to work unchanged. The start_ssl field was previously ignored for IMAP — this fixes that. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
1 parent de08972 commit d92244f

File tree

7 files changed

+821
-152
lines changed

7 files changed

+821
-152
lines changed

‎README.md‎

Lines changed: 62 additions & 19 deletions
Original file line numberDiff line numberDiff line change
@@ -63,24 +63,36 @@ You can also configure the email server using environment variables, which is pa
6363

6464
#### Available Environment Variables
6565

66-
| Variable | Description | Default | Required |
67-
| --------------------------------------------- | ------------------------------------------------- | ------------- | -------- |
68-
| `MCP_EMAIL_SERVER_ACCOUNT_NAME` | Account identifier | `"default"` | No |
69-
| `MCP_EMAIL_SERVER_FULL_NAME` | Display name | Email prefix | No |
70-
| `MCP_EMAIL_SERVER_EMAIL_ADDRESS` | Email address | - | Yes |
71-
| `MCP_EMAIL_SERVER_USER_NAME` | Login username | Same as email | No |
72-
| `MCP_EMAIL_SERVER_PASSWORD` | Email password | - | Yes |
73-
| `MCP_EMAIL_SERVER_IMAP_HOST` | IMAP server host | - | Yes |
74-
| `MCP_EMAIL_SERVER_IMAP_PORT` | IMAP server port | `993` | No |
75-
| `MCP_EMAIL_SERVER_IMAP_SSL` | Enable IMAP SSL | `true` | No |
76-
| `MCP_EMAIL_SERVER_SMTP_HOST` | SMTP server host | - | Yes |
77-
| `MCP_EMAIL_SERVER_SMTP_PORT` | SMTP server port | `465` | No |
78-
| `MCP_EMAIL_SERVER_SMTP_SSL` | Enable SMTP SSL | `true` | No |
79-
| `MCP_EMAIL_SERVER_SMTP_START_SSL` | Enable STARTTLS | `false` | No |
80-
| `MCP_EMAIL_SERVER_SMTP_VERIFY_SSL` | Verify SSL certificates (disable for self-signed) | `true` | No |
81-
| `MCP_EMAIL_SERVER_ENABLE_ATTACHMENT_DOWNLOAD` | Enable attachment download | `false` | No |
82-
| `MCP_EMAIL_SERVER_SAVE_TO_SENT` | Save sent emails to IMAP Sent folder | `true` | No |
83-
| `MCP_EMAIL_SERVER_SENT_FOLDER_NAME` | Custom Sent folder name (auto-detect if not set) | - | No |
66+
| Variable | Description | Default | Required |
67+
| --------------------------------------------- | ------------------------------------------------------ | ------------- | -------- |
68+
| `MCP_EMAIL_SERVER_ACCOUNT_NAME` | Account identifier | `"default"` | No |
69+
| `MCP_EMAIL_SERVER_FULL_NAME` | Display name | Email prefix | No |
70+
| `MCP_EMAIL_SERVER_EMAIL_ADDRESS` | Email address | - | Yes |
71+
| `MCP_EMAIL_SERVER_USER_NAME` | Login username | Same as email | No |
72+
| `MCP_EMAIL_SERVER_PASSWORD` | Email password | - | Yes |
73+
| `MCP_EMAIL_SERVER_IMAP_HOST` | IMAP server host | - | Yes |
74+
| `MCP_EMAIL_SERVER_IMAP_PORT` | IMAP server port | `993` | No |
75+
| `MCP_EMAIL_SERVER_IMAP_SECURITY` | IMAP connection security: `tls`, `starttls`, or `none` | `tls` | No |
76+
| `MCP_EMAIL_SERVER_IMAP_VERIFY_SSL` | Verify IMAP SSL certificates | `true` | No |
77+
| `MCP_EMAIL_SERVER_SMTP_HOST` | SMTP server host | - | Yes |
78+
| `MCP_EMAIL_SERVER_SMTP_PORT` | SMTP server port | `465` | No |
79+
| `MCP_EMAIL_SERVER_SMTP_SECURITY` | SMTP connection security: `tls`, `starttls`, or `none` | `tls` | No |
80+
| `MCP_EMAIL_SERVER_SMTP_VERIFY_SSL` | Verify SMTP SSL certificates | `true` | No |
81+
| `MCP_EMAIL_SERVER_ENABLE_ATTACHMENT_DOWNLOAD` | Enable attachment download | `false` | No |
82+
| `MCP_EMAIL_SERVER_SAVE_TO_SENT` | Save sent emails to IMAP Sent folder | `true` | No |
83+
| `MCP_EMAIL_SERVER_SENT_FOLDER_NAME` | Custom Sent folder name (auto-detect if not set) | - | No |
84+
85+
> **Deprecated:** `MCP_EMAIL_SERVER_IMAP_SSL`, `MCP_EMAIL_SERVER_SMTP_SSL`, and `MCP_EMAIL_SERVER_SMTP_START_SSL` still work for backward compatibility but are superseded by the `*_SECURITY` variables above.
86+
87+
#### Connection Security Modes
88+
89+
The `security` field (or `*_SECURITY` env var) controls how the connection to the mail server is encrypted, per [RFC 8314](https://tools.ietf.org/html/rfc8314):
90+
91+
| Mode | Description | IMAP Port | SMTP Port |
92+
| ---------- | ----------------------------------------------------- | --------- | --------- |
93+
| `tls` | **Implicit TLS** — encrypted from the first byte | 993 | 465 |
94+
| `starttls` | **STARTTLS** — connect plaintext, then upgrade to TLS | 143 | 587 |
95+
| `none` | **No encryption** — plaintext only (not recommended) | 143 | 25 |
8496

8597
### Enabling Attachment Downloads
8698

@@ -153,7 +165,7 @@ sent_folder_name = "INBOX.Sent"
153165

154166
### Self-Signed Certificates (e.g., ProtonMail Bridge)
155167

156-
If you're using a local mail server with self-signed certificates (like ProtonMail Bridge), you'll need to disable SSL certificate verification:
168+
If you're using a local mail server with self-signed certificates (like ProtonMail Bridge), you'll need to disable SSL certificate verification for both IMAP and SMTP:
157169

158170
```json
159171
{
@@ -162,6 +174,7 @@ If you're using a local mail server with self-signed certificates (like ProtonMa
162174
"command": "uvx",
163175
"args": ["mcp-email-server@latest", "stdio"],
164176
"env": {
177+
"MCP_EMAIL_SERVER_IMAP_VERIFY_SSL": "false",
165178
"MCP_EMAIL_SERVER_SMTP_VERIFY_SSL": "false"
166179
}
167180
}
@@ -176,7 +189,37 @@ Or in TOML configuration:
176189
account_name = "protonmail"
177190
# ... other settings ...
178191

192+
[emails.incoming]
193+
verify_ssl = false
194+
195+
[emails.outgoing]
196+
verify_ssl = false
197+
```
198+
199+
#### ProtonMail Bridge Example
200+
201+
ProtonMail Bridge uses STARTTLS on local ports with self-signed certificates:
202+
203+
```toml
204+
[[emails]]
205+
account_name = "protonmail"
206+
full_name = "Your Name"
207+
email_address = "you@proton.me"
208+
209+
[emails.incoming]
210+
host = "127.0.0.1"
211+
port = 1143
212+
user_name = "you@proton.me"
213+
password = "your-bridge-password"
214+
security = "starttls"
215+
verify_ssl = false
216+
179217
[emails.outgoing]
218+
host = "127.0.0.1"
219+
port = 1025
220+
user_name = "you@proton.me"
221+
password = "your-bridge-password"
222+
security = "starttls"
180223
verify_ssl = false
181224
```
182225

0 commit comments

Comments
 (0)