feat: Add email reply support with In-Reply-To and References headers (#80)

* feat(models): add message_id field for reply threading

* feat(parsing): extract Message-ID header for reply threading

* feat(send): add in_reply_to and references parameters for threading

* feat(handler): pass reply headers through ClassicEmailHandler

* feat(mcp): add in_reply_to and references params to send_email tool

* feat(content): include message_id in EmailBodyResponse

* docs: add reply/threading usage example

* style: apply formatter fixes

* chore: remove accidentally committed config.toml

* chore: add config.toml to gitignore

* drop useless docs

---------

Co-authored-by: Wh1isper <9573586@qq.com>

Author: Pillumz

.gitignore

@@ -141,3 +141,4 @@ cython_debug/
 
 tests/config.toml
 local/
+config.toml

README.md

@@ -189,6 +189,34 @@ To install Email Server for Claude Desktop automatically via [Smithery](https://
 npx -y @smithery/cli install @ai-zerolab/mcp-email-server --client claude
 ```
 
+## Usage
+
+### Replying to Emails
+
+To reply to an email with proper threading (so it appears in the same conversation in email clients):
+
+1. First, fetch the original email to get its `message_id`:
+
+```python
+emails = await get_emails_content(account_name="work", email_ids=["123"])
+original = emails.emails[0]
+```
+
+2. Send your reply using `in_reply_to` and `references`:
+
+```python
+await send_email(
+    account_name="work",
+    recipients=[original.sender],
+    subject=f"Re: {original.subject}",
+    body="Thank you for your email...",
+    in_reply_to=original.message_id,
+    references=original.message_id,
+)
+```
+
+The `in_reply_to` parameter sets the `In-Reply-To` header, and `references` sets the `References` header. Both are used by email clients to thread conversations properly.
+
 ## Development
 
 This project is managed using [uv](https://github.com/ai-zerolab/uv).

mcp_email_server/app.py

@@ -103,7 +103,7 @@ async def get_emails_content(
 
 
 @mcp.tool(
-    description="Send an email using the specified account. Recipient should be a list of email addresses. Optionally attach files by providing their absolute paths.",
+    description="Send an email using the specified account. Supports replying to emails with proper threading when in_reply_to is provided.",
 )
 async def send_email(
     account_name: Annotated[str, Field(description="The name of the email account to send from.")],
@@ -129,9 +129,33 @@ async def send_email(
             description="A list of absolute file paths to attach to the email. Supports common file types (documents, images, archives, etc.).",
         ),
     ] = None,
+    in_reply_to: Annotated[
+        str | None,
+        Field(
+            default=None,
+            description="Message-ID of the email being replied to. Enables proper threading in email clients.",
+        ),
+    ] = None,
+    references: Annotated[
+        str | None,
+        Field(
+            default=None,
+            description="Space-separated Message-IDs for the thread chain. Usually includes in_reply_to plus ancestors.",
+        ),
+    ] = None,
 ) -> str:
     handler = dispatch_handler(account_name)
-    await handler.send_email(recipients, subject, body, cc, bcc, html, attachments)
+    await handler.send_email(
+        recipients,
+        subject,
+        body,
+        cc,
+        bcc,
+        html,
+        attachments,
+        in_reply_to,
+        references,
+    )
     recipient_str = ", ".join(recipients)
     attachment_info = f" with {len(attachments)} attachment(s)" if attachments else ""
     return f"Email sent successfully to {recipient_str}{attachment_info}"

mcp_email_server/emails/classic.py

@@ -46,6 +46,9 @@ def _parse_email_data(self, raw_email: bytes, email_id: str | None = None) -> di
         sender = email_message.get("From", "")
         date_str = email_message.get("Date", "")
 
+        # Extract Message-ID for reply threading
+        message_id = email_message.get("Message-ID")
+
         # Extract recipients
         to_addresses = []
         to_header = email_message.get("To", "")
@@ -106,6 +109,7 @@ def _parse_email_data(self, raw_email: bytes, email_id: str | None = None) -> di
             body = body[:20000] + "...[TRUNCATED]"
         return {
             "email_id": email_id or "",
+            "message_id": message_id,
             "subject": subject,
             "from": sender,
             "to": to_addresses,
@@ -528,6 +532,8 @@ async def send_email(
         bcc: list[str] | None = None,
         html: bool = False,
         attachments: list[str] | None = None,
+        in_reply_to: str | None = None,
+        references: str | None = None,
     ):
         # Create message with or without attachments
         if attachments:
@@ -554,6 +560,12 @@ async def send_email(
         if cc:
             msg["Cc"] = ", ".join(cc)
 
+        # Set threading headers for replies
+        if in_reply_to:
+            msg["In-Reply-To"] = in_reply_to
+        if references:
+            msg["References"] = references
+
         # Note: BCC recipients are not added to headers (they remain hidden)
         # but will be included in the actual recipients for SMTP delivery
 
@@ -742,6 +754,7 @@ async def get_emails_content(self, email_ids: list[str], mailbox: str = "INBOX")
                     emails.append(
                         EmailBodyResponse(
                             email_id=email_data["email_id"],
+                            message_id=email_data.get("message_id"),
                             subject=email_data["subject"],
                             sender=email_data["from"],
                             recipients=email_data["to"],
@@ -772,8 +785,12 @@ async def send_email(
         bcc: list[str] | None = None,
         html: bool = False,
         attachments: list[str] | None = None,
+        in_reply_to: str | None = None,
+        references: str | None = None,
     ) -> None:
-        msg = 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, in_reply_to, references
+        )
 
         # Save to Sent folder if enabled
         if self.save_to_sent and msg:

mcp_email_server/emails/models.py

@@ -8,6 +8,7 @@ class EmailMetadata(BaseModel):
     """Email metadata"""
 
     email_id: str
+    message_id: str | None = None  # RFC 5322 Message-ID header for reply threading
     subject: str
     sender: str
     recipients: list[str]  # Recipient list
@@ -18,6 +19,7 @@ class EmailMetadata(BaseModel):
     def from_email(cls, email: dict[str, Any]):
         return cls(
             email_id=email["email_id"],
+            message_id=email.get("message_id"),
             subject=email["subject"],
             sender=email["from"],
             recipients=email.get("to", []),
@@ -42,6 +44,7 @@ class EmailBodyResponse(BaseModel):
     """Single email body response"""
 
     email_id: str  # IMAP UID of this email
+    message_id: str | None = None  # RFC 5322 Message-ID header for reply threading
     subject: str
     sender: str
     recipients: list[str]

tests/test_classic_handler.py

@@ -5,7 +5,13 @@
 
 from mcp_email_server.config import EmailServer, EmailSettings
 from mcp_email_server.emails.classic import ClassicEmailHandler, EmailClient
-from mcp_email_server.emails.models import AttachmentDownloadResponse, EmailMetadata, EmailMetadataPageResponse
+from mcp_email_server.emails.models import (
+    AttachmentDownloadResponse,
+    EmailBodyResponse,
+    EmailContentBatchResponse,
+    EmailMetadata,
+    EmailMetadataPageResponse,
+)
 
 
 @pytest.fixture
@@ -168,6 +174,8 @@ async def test_send_email(self, classic_handler):
                 ["bcc@example.com"],
                 False,
                 None,
+                None,
+                None,
             )
 
     @pytest.mark.asyncio
@@ -199,6 +207,8 @@ async def test_send_email_with_attachments(self, classic_handler, tmp_path):
                 None,
                 False,
                 [str(test_file)],
+                None,
+                None,
             )
 
     @pytest.mark.asyncio
@@ -276,3 +286,63 @@ async def test_download_attachment(self, classic_handler, tmp_path):
             assert result.saved_path == save_path
 
             mock_download.assert_called_once_with("123", "document.pdf", save_path)
+
+    @pytest.mark.asyncio
+    async def test_send_email_with_reply_headers(self, classic_handler):
+        """Test sending email with reply headers."""
+        mock_smtp = AsyncMock()
+        mock_smtp.__aenter__.return_value = mock_smtp
+        mock_smtp.__aexit__.return_value = None
+        mock_smtp.login = AsyncMock()
+        mock_smtp.send_message = AsyncMock()
+
+        with patch("aiosmtplib.SMTP", return_value=mock_smtp):
+            await classic_handler.send_email(
+                recipients=["recipient@example.com"],
+                subject="Re: Test",
+                body="Reply body",
+                in_reply_to="<original@example.com>",
+                references="<original@example.com>",
+            )
+
+            call_args = mock_smtp.send_message.call_args
+            msg = call_args[0][0]
+            assert msg["In-Reply-To"] == "<original@example.com>"
+            assert msg["References"] == "<original@example.com>"
+
+    @pytest.mark.asyncio
+    async def test_get_emails_content_includes_message_id(self, classic_handler):
+        """Test that get_emails_content returns message_id from parsed email data."""
+        now = datetime.now(timezone.utc)
+        email_data = {
+            "email_id": "123",
+            "message_id": "<test-message-id@example.com>",
+            "subject": "Test Subject",
+            "from": "sender@example.com",
+            "to": ["recipient@example.com"],
+            "date": now,
+            "body": "Test email body",
+            "attachments": [],
+        }
+
+        # Mock the get_email_body_by_id method to return our test data
+        mock_get_body = AsyncMock(return_value=email_data)
+
+        with patch.object(classic_handler.incoming_client, "get_email_body_by_id", mock_get_body):
+            result = await classic_handler.get_emails_content(
+                email_ids=["123"],
+                mailbox="INBOX",
+            )
+
+            # Verify the result
+            assert isinstance(result, EmailContentBatchResponse)
+            assert len(result.emails) == 1
+            assert isinstance(result.emails[0], EmailBodyResponse)
+            assert result.emails[0].email_id == "123"
+            assert result.emails[0].message_id == "<test-message-id@example.com>"
+            assert result.emails[0].subject == "Test Subject"
+            assert result.emails[0].sender == "sender@example.com"
+            assert result.emails[0].body == "Test email body"
+
+            # Verify the client method was called correctly
+            mock_get_body.assert_called_once_with("123", "INBOX")

tests/test_email_client.py

@@ -262,3 +262,95 @@ async def test_send_email(self, email_client):
             assert "recipient@example.com" in recipients
             assert "cc@example.com" in recipients
             assert "bcc@example.com" in recipients
+
+
+class TestParseEmailData:
+    def test_parse_email_extracts_message_id(self, email_client):
+        """Test that Message-ID header is extracted during parsing."""
+        raw_email = b"""Message-ID: <test123@example.com>
+From: sender@example.com
+To: recipient@example.com
+Subject: Test Subject
+Date: Mon, 1 Jan 2024 12:00:00 +0000
+
+Test body content
+"""
+        result = email_client._parse_email_data(raw_email, email_id="1")
+        assert result["message_id"] == "<test123@example.com>"
+
+    def test_parse_email_handles_missing_message_id(self, email_client):
+        """Test graceful handling when Message-ID is missing."""
+        raw_email = b"""From: sender@example.com
+To: recipient@example.com
+Subject: Test Subject
+Date: Mon, 1 Jan 2024 12:00:00 +0000
+
+Test body content
+"""
+        result = email_client._parse_email_data(raw_email, email_id="1")
+        assert result["message_id"] is None
+
+
+class TestSendEmailReplyHeaders:
+    @pytest.mark.asyncio
+    async def test_send_email_sets_in_reply_to_header(self, email_client):
+        """Test that In-Reply-To header is set when provided."""
+        mock_smtp = AsyncMock()
+        mock_smtp.__aenter__.return_value = mock_smtp
+        mock_smtp.__aexit__.return_value = None
+        mock_smtp.login = AsyncMock()
+        mock_smtp.send_message = AsyncMock()
+
+        with patch("aiosmtplib.SMTP", return_value=mock_smtp):
+            await email_client.send_email(
+                recipients=["recipient@example.com"],
+                subject="Re: Test",
+                body="Reply body",
+                in_reply_to="<original123@example.com>",
+            )
+
+            call_args = mock_smtp.send_message.call_args
+            msg = call_args[0][0]
+            assert msg["In-Reply-To"] == "<original123@example.com>"
+
+    @pytest.mark.asyncio
+    async def test_send_email_sets_references_header(self, email_client):
+        """Test that References header is set when provided."""
+        mock_smtp = AsyncMock()
+        mock_smtp.__aenter__.return_value = mock_smtp
+        mock_smtp.__aexit__.return_value = None
+        mock_smtp.login = AsyncMock()
+        mock_smtp.send_message = AsyncMock()
+
+        with patch("aiosmtplib.SMTP", return_value=mock_smtp):
+            await email_client.send_email(
+                recipients=["recipient@example.com"],
+                subject="Re: Test",
+                body="Reply body",
+                references="<first@example.com> <second@example.com>",
+            )
+
+            call_args = mock_smtp.send_message.call_args
+            msg = call_args[0][0]
+            assert msg["References"] == "<first@example.com> <second@example.com>"
+
+    @pytest.mark.asyncio
+    async def test_send_email_without_reply_headers(self, email_client):
+        """Test that send works without reply headers (backward compatibility)."""
+        mock_smtp = AsyncMock()
+        mock_smtp.__aenter__.return_value = mock_smtp
+        mock_smtp.__aexit__.return_value = None
+        mock_smtp.login = AsyncMock()
+        mock_smtp.send_message = AsyncMock()
+
+        with patch("aiosmtplib.SMTP", return_value=mock_smtp):
+            await email_client.send_email(
+                recipients=["recipient@example.com"],
+                subject="Test",
+                body="Body",
+            )
+
+            call_args = mock_smtp.send_message.call_args
+            msg = call_args[0][0]
+            assert "In-Reply-To" not in msg
+            assert "References" not in msg