feat: add mailbox parameter to download_attachment method

[Wh1isper]

Summary

This PR adds a mailbox parameter to the download_attachment method, enabling users to download attachments from any mailbox instead of being restricted to INBOX.

Problem

Previously, download_attachment was hardcoded to use INBOX:

await imap.select(_quote_mailbox("INBOX"))

However, other methods in the same class accept a mailbox parameter with INBOX as the default:

• get_email_count(mailbox: str = "INBOX")
• get_emails_metadata_stream(mailbox: str = "INBOX")
• get_email_body_by_id(mailbox: str = "INBOX")
• delete_emails(email_ids, mailbox: str = "INBOX")

This inconsistency prevents users from downloading attachments from other mailboxes like "All Mail", "Sent", or "[Gmail]/Sent Mail".

Solution

Add consistent mailbox parameter support to download_attachment across all layers:

1. EmailClient.download_attachment() - Core implementation with mailbox parameter
2. ClassicEmailHandler.download_attachment() - Handler layer with mailbox parameter
3. Abstract EmailHandler.download_attachment() - Interface definition with mailbox parameter
4. MCP tool download_attachment() - Exposed to AI agents with mailbox parameter

Changes

Code Changes

• mcp_email_server/emails/classic.py:

  • Added mailbox: str = "INBOX" parameter to EmailClient.download_attachment()
  • Added mailbox: str = "INBOX" parameter to ClassicEmailHandler.download_attachment()
  • Updated docstrings with Args section

• mcp_email_server/emails/init.py:

  • Added mailbox: str = "INBOX" parameter to abstract EmailHandler.download_attachment()
  • Updated docstring

• mcp_email_server/app.py:

  • Added mailbox parameter to MCP tool download_attachment()

Test Changes

• tests/test_email_attachments.py: Added 3 new tests for mailbox parameter
• tests/test_classic_handler.py: Updated assertion for new parameter
• tests/test_mcp_tools.py: Updated assertion for new parameter

Testing

• ✅ All 101 tests pass
• ✅ make check passes (ruff formatting, linting, dependency checks)

Backward Compatibility

✅ Fully backward compatible. The new parameter has a default value of "INBOX", so existing code will continue to work unchanged.

Usage Example

# Download from INBOX (default, existing behavior)
await handler.download_attachment("123", "document.pdf", "/path/to/save")

# Download from a custom mailbox (new capability)
await handler.download_attachment("456", "report.pdf", "/path/to/save", mailbox="All Mail")
await handler.download_attachment("789", "invoice.pdf", "/path/to/save", mailbox="[Gmail]/Sent Mail")

Checklist

• Code follows project style guidelines
• Tests added for new functionality
• All tests passing (101/101)
• make check passes
• Backward compatibility maintained
• Documentation updated (docstrings)

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!