feat: add save_to_sent option to save sent emails to IMAP Sent folder (#82)

* feat: add save_to_sent option to save sent emails to IMAP Sent folder

- Add save_to_sent config option (default: true) to EmailSettings
- Add sent_folder_name config option for custom Sent folder names
- Implement IMAP APPEND after successful SMTP send
- Auto-detect common Sent folder names across providers
- Support env vars MCP_EMAIL_SERVER_SAVE_TO_SENT and MCP_EMAIL_SERVER_SENT_FOLDER_NAME
- Update README with documentation for new feature

Closes #81

* [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci

* fix: exclude None values when serializing to TOML

TOML doesn't support None values, so use exclude_none=True in model_dump()

* test: add comprehensive tests for save_to_sent feature

- Test save_to_sent and sent_folder_name config options
- Test environment variable configuration
- Test ClassicEmailHandler initialization with save_to_sent
- Test send_email calls append_to_sent when enabled
- Test append_to_sent with various scenarios (success, failure, auto-detect)

* style: fix linting and formatting in test file

---------

Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com>

Author: cleanspin

README.md

@@ -63,21 +63,23 @@ You can also configure the email server using environment variables, which is pa
 
 #### Available Environment Variables
 
-| Variable                                      | Description                | Default       | Required |
-| --------------------------------------------- | -------------------------- | ------------- | -------- |
-| `MCP_EMAIL_SERVER_ACCOUNT_NAME`               | Account identifier         | `"default"`   | No       |
-| `MCP_EMAIL_SERVER_FULL_NAME`                  | Display name               | Email prefix  | No       |
-| `MCP_EMAIL_SERVER_EMAIL_ADDRESS`              | Email address              | -             | Yes      |
-| `MCP_EMAIL_SERVER_USER_NAME`                  | Login username             | Same as email | No       |
-| `MCP_EMAIL_SERVER_PASSWORD`                   | Email password             | -             | Yes      |
-| `MCP_EMAIL_SERVER_IMAP_HOST`                  | IMAP server host           | -             | Yes      |
-| `MCP_EMAIL_SERVER_IMAP_PORT`                  | IMAP server port           | `993`         | No       |
-| `MCP_EMAIL_SERVER_IMAP_SSL`                   | Enable IMAP SSL            | `true`        | No       |
-| `MCP_EMAIL_SERVER_SMTP_HOST`                  | SMTP server host           | -             | Yes      |
-| `MCP_EMAIL_SERVER_SMTP_PORT`                  | SMTP server port           | `465`         | No       |
-| `MCP_EMAIL_SERVER_SMTP_SSL`                   | Enable SMTP SSL            | `true`        | No       |
-| `MCP_EMAIL_SERVER_SMTP_START_SSL`             | Enable STARTTLS            | `false`       | No       |
-| `MCP_EMAIL_SERVER_ENABLE_ATTACHMENT_DOWNLOAD` | Enable attachment download | `false`       | No       |
+| Variable                                      | Description                                      | Default       | Required |
+| --------------------------------------------- | ------------------------------------------------ | ------------- | -------- |
+| `MCP_EMAIL_SERVER_ACCOUNT_NAME`               | Account identifier                               | `"default"`   | No       |
+| `MCP_EMAIL_SERVER_FULL_NAME`                  | Display name                                     | Email prefix  | No       |
+| `MCP_EMAIL_SERVER_EMAIL_ADDRESS`              | Email address                                    | -             | Yes      |
+| `MCP_EMAIL_SERVER_USER_NAME`                  | Login username                                   | Same as email | No       |
+| `MCP_EMAIL_SERVER_PASSWORD`                   | Email password                                   | -             | Yes      |
+| `MCP_EMAIL_SERVER_IMAP_HOST`                  | IMAP server host                                 | -             | Yes      |
+| `MCP_EMAIL_SERVER_IMAP_PORT`                  | IMAP server port                                 | `993`         | No       |
+| `MCP_EMAIL_SERVER_IMAP_SSL`                   | Enable IMAP SSL                                  | `true`        | No       |
+| `MCP_EMAIL_SERVER_SMTP_HOST`                  | SMTP server host                                 | -             | Yes      |
+| `MCP_EMAIL_SERVER_SMTP_PORT`                  | SMTP server port                                 | `465`         | No       |
+| `MCP_EMAIL_SERVER_SMTP_SSL`                   | Enable SMTP SSL                                  | `true`        | No       |
+| `MCP_EMAIL_SERVER_SMTP_START_SSL`             | Enable STARTTLS                                  | `false`       | No       |
+| `MCP_EMAIL_SERVER_ENABLE_ATTACHMENT_DOWNLOAD` | Enable attachment download                       | `false`       | No       |
+| `MCP_EMAIL_SERVER_SAVE_TO_SENT`               | Save sent emails to IMAP Sent folder             | `true`        | No       |
+| `MCP_EMAIL_SERVER_SENT_FOLDER_NAME`           | Custom Sent folder name (auto-detect if not set) | -             | No       |
 
 ### Enabling Attachment Downloads
 
@@ -112,6 +114,42 @@ enable_attachment_download = true
 
 Once enabled, you can use the `download_attachment` tool to save email attachments to a specified path.
 
+### Saving Sent Emails to IMAP Sent Folder
+
+By default, sent emails are automatically saved to your IMAP Sent folder. This ensures that emails sent via the MCP server appear in your email client (Thunderbird, webmail, etc.).
+
+The server auto-detects common Sent folder names: `Sent`, `INBOX.Sent`, `Sent Items`, `Sent Mail`, `[Gmail]/Sent Mail`.
+
+**To specify a custom Sent folder name** (useful for providers with non-standard folder names):
+
+**Option 1: Environment Variable**
+
+```json
+{
+  "mcpServers": {
+    "zerolib-email": {
+      "command": "uvx",
+      "args": ["mcp-email-server@latest", "stdio"],
+      "env": {
+        "MCP_EMAIL_SERVER_SENT_FOLDER_NAME": "INBOX.Sent"
+      }
+    }
+  }
+}
+```
+
+**Option 2: TOML Configuration**
+
+```toml
+[[emails]]
+account_name = "work"
+save_to_sent = true
+sent_folder_name = "INBOX.Sent"
+# ... rest of your email configuration
+```
+
+**To disable saving to Sent folder**, set `MCP_EMAIL_SERVER_SAVE_TO_SENT=false` or `save_to_sent = false` in your TOML config.
+
 For separate IMAP/SMTP credentials, you can also use:
 
 - `MCP_EMAIL_SERVER_IMAP_USER_NAME` / `MCP_EMAIL_SERVER_IMAP_PASSWORD`

mcp_email_server/config.py

@@ -75,6 +75,8 @@ class EmailSettings(AccountAttributes):
     email_address: str
     incoming: EmailServer
     outgoing: EmailServer
+    save_to_sent: bool = True  # Save sent emails to IMAP Sent folder
+    sent_folder_name: str | None = None  # Override Sent folder name (auto-detect if None)
 
     @classmethod
     def init(
@@ -96,6 +98,8 @@ def init(
         smtp_start_ssl: bool = False,
         smtp_user_name: str | None = None,
         smtp_password: str | None = None,
+        save_to_sent: bool = True,
+        sent_folder_name: str | None = None,
     ) -> EmailSettings:
         return cls(
             account_name=account_name,
@@ -116,6 +120,8 @@ def init(
                 use_ssl=smtp_ssl,
                 start_ssl=smtp_start_ssl,
             ),
+            save_to_sent=save_to_sent,
+            sent_folder_name=sent_folder_name,
         )
 
     @classmethod
@@ -135,6 +141,8 @@ def from_env(cls) -> EmailSettings | None:
         - MCP_EMAIL_SERVER_SMTP_PORT (default: 465)
         - MCP_EMAIL_SERVER_SMTP_SSL (default: true)
         - MCP_EMAIL_SERVER_SMTP_START_SSL (default: false)
+        - MCP_EMAIL_SERVER_SAVE_TO_SENT (default: true)
+        - MCP_EMAIL_SERVER_SENT_FOLDER_NAME (default: auto-detect)
         """
         # Check if minimum required environment variables are set
         email_address = os.getenv("MCP_EMAIL_SERVER_EMAIL_ADDRESS")
@@ -179,6 +187,8 @@ def parse_bool(value: str | None, default: bool = True) -> bool:
                 smtp_password=os.getenv("MCP_EMAIL_SERVER_SMTP_PASSWORD", password),
                 imap_user_name=os.getenv("MCP_EMAIL_SERVER_IMAP_USER_NAME", user_name),
                 imap_password=os.getenv("MCP_EMAIL_SERVER_IMAP_PASSWORD", password),
+                save_to_sent=parse_bool(os.getenv("MCP_EMAIL_SERVER_SAVE_TO_SENT"), True),
+                sent_folder_name=os.getenv("MCP_EMAIL_SERVER_SENT_FOLDER_NAME"),
             )
         except (ValueError, TypeError) as e:
             logger.error(f"Failed to create email settings from environment variables: {e}")
@@ -303,7 +313,7 @@ def settings_customise_sources(
         return (TomlConfigSettingsSource(settings_cls),)
 
     def _to_toml(self) -> str:
-        data = self.model_dump()
+        data = self.model_dump(exclude_none=True)
         return tomli_w.dumps(data)
 
     def store(self) -> None:

mcp_email_server/emails/classic.py

@@ -574,6 +574,91 @@ async def send_email(
 
             await smtp.send_message(msg, recipients=all_recipients)
 
+        # Return the message for potential saving to Sent folder
+        return msg
+
+    async def append_to_sent(
+        self,
+        msg: MIMEText | MIMEMultipart,
+        incoming_server: EmailServer,
+        sent_folder_name: str | None = None,
+    ) -> bool:
+        """Append a sent message to the IMAP Sent folder.
+
+        Args:
+            msg: The email message that was sent
+            incoming_server: IMAP server configuration for accessing Sent folder
+            sent_folder_name: Override folder name, or None for auto-detection
+
+        Returns:
+            True if successfully saved, False otherwise
+        """
+        imap_class = aioimaplib.IMAP4_SSL if incoming_server.use_ssl else aioimaplib.IMAP4
+        imap = imap_class(incoming_server.host, incoming_server.port)
+
+        # Common Sent folder names across different providers
+        sent_folder_candidates = [
+            sent_folder_name,  # User-specified override (if provided)
+            "Sent",
+            "INBOX.Sent",
+            "Sent Items",
+            "Sent Mail",
+            "[Gmail]/Sent Mail",
+            "INBOX/Sent",
+        ]
+        # Filter out None values
+        sent_folder_candidates = [f for f in sent_folder_candidates if f]
+
+        try:
+            await imap._client_task
+            await imap.wait_hello_from_server()
+            await imap.login(incoming_server.user_name, incoming_server.password)
+
+            # Try to find and use the Sent folder
+            for folder in sent_folder_candidates:
+                try:
+                    logger.debug(f"Trying Sent folder: '{folder}'")
+                    # Try to select the folder to verify it exists
+                    result = await imap.select(folder)
+                    logger.debug(f"Select result for '{folder}': {result}")
+
+                    # aioimaplib returns (status, data) where status is a string like 'OK' or 'NO'
+                    status = result[0] if isinstance(result, tuple) else result
+                    if str(status).upper() == "OK":
+                        # Folder exists, append the message
+                        msg_bytes = msg.as_bytes()
+                        logger.debug(f"Appending message to '{folder}'")
+                        # aioimaplib.append signature: (message_bytes, mailbox, flags, date)
+                        append_result = await imap.append(
+                            msg_bytes,
+                            mailbox=folder,
+                            flags=r"(\Seen)",
+                        )
+                        logger.debug(f"Append result: {append_result}")
+                        append_status = append_result[0] if isinstance(append_result, tuple) else append_result
+                        if str(append_status).upper() == "OK":
+                            logger.info(f"Saved sent email to '{folder}'")
+                            return True
+                        else:
+                            logger.warning(f"Failed to append to '{folder}': {append_status}")
+                    else:
+                        logger.debug(f"Folder '{folder}' select returned: {status}")
+                except Exception as e:
+                    logger.debug(f"Folder '{folder}' not available: {e}")
+                    continue
+
+            logger.warning("Could not find a valid Sent folder to save the message")
+            return False
+
+        except Exception as e:
+            logger.error(f"Error saving to Sent folder: {e}")
+            return False
+        finally:
+            try:
+                await imap.logout()
+            except Exception as e:
+                logger.debug(f"Error during logout: {e}")
+
     async def delete_emails(self, email_ids: list[str], mailbox: str = "INBOX") -> tuple[list[str], list[str]]:
         """Delete emails by their UIDs. Returns (deleted_ids, failed_ids)."""
         imap = self.imap_class(self.email_server.host, self.email_server.port)
@@ -612,6 +697,8 @@ def __init__(self, email_settings: EmailSettings):
             email_settings.outgoing,
             sender=f"{email_settings.full_name} <{email_settings.email_address}>",
         )
+        self.save_to_sent = email_settings.save_to_sent
+        self.sent_folder_name = email_settings.sent_folder_name
 
     async def get_emails_metadata(
         self,
@@ -686,7 +773,15 @@ async def send_email(
         html: bool = False,
         attachments: list[str] | None = None,
     ) -> None:
-        await self.outgoing_client.send_email(recipients, subject, body, cc, bcc, html, attachments)
+        msg = await self.outgoing_client.send_email(recipients, subject, body, cc, bcc, html, attachments)
+
+        # Save to Sent folder if enabled
+        if self.save_to_sent and msg:
+            await self.outgoing_client.append_to_sent(
+                msg,
+                self.email_settings.incoming,
+                self.sent_folder_name,
+            )
 
     async def delete_emails(self, email_ids: list[str], mailbox: str = "INBOX") -> tuple[list[str], list[str]]:
         """Delete emails by their UIDs. Returns (deleted_ids, failed_ids)."""