feat: plan MailThunder 2.0 email automation and integration layer

[JE-Chen]

Summary

This draft PR proposes the MailThunder 2.0 architecture and implementation roadmap.

The goal is to evolve MailThunder from a SMTP/IMAP-oriented email utility into a provider-agnostic Python Email Automation & Integration Framework.

Scope

• UI redesign / MailThunder Studio
• Complete PyPI metadata and project description
• OAuth2 / XOAUTH2 authentication
• Reusable subject/text/HTML email templates
• Attachment size/type guards and security policies
• Microsoft Graph provider
• Provider-independent mail triggers and events
• IMAP polling / IDLE and Graph polling / webhook trigger backends
• Project-level Mail Layer for Automation projects
• Backward compatibility for existing SMTPWrapper / IMAPWrapper APIs
• Documentation, migration guidance and testing strategy

Architecture

Automation Projects
        |
 Project Mail Layer
        |
    MailThunder
        |
 +------+------+------+
 |      |      |      |
SMTP   IMAP   Graph  Triggers
 |      |      |      |
OAuth2 OAuth2 OAuth2  Events

The proposed Core API keeps applications independent of the underlying mail provider.

Implementation Priority

P0 — Foundation

• Core Mail API
• Provider interface
• Authentication abstraction
• OAuth2 / XOAUTH2
• AttachmentPolicy
• PyPI metadata
• Backward compatibility

P1 — Email Platform

• Template Engine
• Microsoft Graph provider
• Trigger interface / dispatcher
• Structured mail events

P2 — Automation Integration

• IMAP polling / IDLE
• Graph polling / webhook
• Project Mail Layer

P3 — UI

• MailThunder Studio
• Dashboard
• Accounts
• Templates
• Triggers
• Policies
• Projects
• Logs
• Settings

P4 — Advanced

• Webhook/event extensions
• Provider health monitoring
• Audit logging
• Additional providers

Proposed implementation PRs

1. Core architecture + provider interfaces
2. Authentication abstraction
3. OAuth2 / XOAUTH2
4. Attachment policies
5. Template engine
6. Microsoft Graph provider
7. Trigger/event architecture
8. IMAP / Graph trigger backends
9. Project Mail Layer
10. UI redesign
11. Documentation / PyPI
12. Integration tests + migration cleanup

Acceptance Criteria

• Existing MailThunder users can continue using the legacy API
• SMTP and IMAP remain supported
• OAuth2 / XOAUTH2 are available
• Microsoft Graph can send/retrieve mail
• Templates generate subject/text/HTML content
• Attachment validation occurs before sending
• Mail events are provider-independent
• Trigger backends are pluggable
• Automation projects can use MailThunder as their mail layer
• PyPI metadata reflects the new product direction
• UI consumes the Core API
• Unit/integration tests cover the new abstractions
• Migration documentation is available

The detailed architecture and package proposal are documented in docs/MAILTHUNDER-2.0-ROADMAP.md.

This PR is intentionally a Draft for architecture review before implementation is split into focused feature PRs.

[sonarqubecloud]

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud

[codacy-production]

Up to standards ✅

🟢 Issues 0 issues

Results:
0 new issues

View in Codacy

_{NEW Get contextual insights on your PRs based on Codacy's metrics, along with PR and Jira context, without leaving GitHub. Enable AI reviewer
TIP This summary will be updated as you push new changes.}