✨ Features

• Small & Lightweight: Quick installation, no complex dependencies (less than 1MB)
• Easy to Use: Clear and simple API, create beautiful email templates with just a few lines of code
• Complete Documentation: Full documentation with type annotations, comprehensive IDE support
• Rich Components: Currently includes 17 beautiful display components, all following Fluent design principles
• Fully Tested: Core functionality thoroughly tested to ensure reliability
• Completely Free: MIT open source license, use freely in any commercial project

✨ Why Choose EmailWidget?

Want to send alerts or logs to email but don't know how to beautify them? Use EmailWidget to complete the final step of sending emails!

5 lines of code saves you 30 minutes of dealing with various email CSS compatibility issues. Supports PC and mobile devices, making the once painful task of sending alert emails simple. You can build your unique email template like building blocks, send with one line of code, no heavyweight dependencies, completely open source and free for commercial use. Installation is less than 2MB. EmailWidget welcomes you to join your project anytime.

The email style below can be created with just 3 lines of code, and the generated content can be sent directly as an email, with recipients seeing beautiful emails:

from email_widget import Email

email = Email("Welcome to EmailWidget")

email.add_card("Python Version", "You need Python 3.10 or higher to use EmailWidget", metadata={"Python Version": "3.10+"})

email.add_quote("EmailWidget is a Python library for building and sending HTML emails.", "EmailWidget")

email.export_html('welcome_email.html')

🎨 Rich Components - 17 Intuitive Components

# One line of code, multiple components
email.add_widget(TextWidget().set_content("Title").set_type(TextType.TITLE_LARGE))
email.add_widget(TableWidget().set_dataframe(df)) # Supports pandas DataFrame
email.add_widget(ChartWidget().set_chart(plt)) # Supports matplotlib/seaborn charts
email.add_widget(ProgressWidget().set_value(85).set_theme(ProgressTheme.SUCCESS))

# Use shortcut methods to add components directly
email.add_progress(value=95, max_value=100)

🏃‍♂️ Quick Start

📦 Installation

Basic Installation (Recommended)

pip install EmailWidget

💡 Installation Note: Only requires jinja2 dependency, lightweight and fast. If you need DataFrame functionality for TableWidget or Matplotlib for ChartWidget, please install pandas or matplotlib/seaborn separately.

🎯 Create Your First Report in 30 Seconds

from email_widget import Email, TextWidget, ProgressWidget
from email_widget.core.enums import TextType, ProgressTheme

# 1️⃣ Create email object
email = Email("📊 Daily Sales Report")

# 2️⃣ Add subtitle and footer
email.set_subtitle("Q1 2024 Performance Summary")
email.set_footer("This report is automatically generated by the data analysis team")

# 3️⃣ Add a large title
email.add_widget(
    TextWidget().set_content("📈 Sales Performance Overview").set_type(TextType.TITLE_LARGE)
)

# 4️⃣ Add progress indicators
email.add_widget(
    ProgressWidget()
    .set_value(92)
    .set_label("Quarterly Goal Completion Rate")
    .set_theme(ProgressTheme.SUCCESS)
)

# 5️⃣ Add data table (using convenience method, directly call email instead of creating widget then add_widget)
data = [
    ["iPhone 15", "1,250", "$1,875,000", "125%"],
    ["MacBook Pro", "580", "$1,740,000", "116%"],
    ["iPad Air", "920", "$552,000", "108%"],
]
email.add_table_from_data(
    data=data, headers=["Product", "Sales", "Revenue", "Achievement Rate"], title="🏆 Product Sales Details"
)

# 6️⃣ Export HTML file
file_path = email.export_html("daily_report.html")
# If you need to send email directly, export to string interface is also provided (images are automatically converted to base64 embedded in html)
# html_str: str = email.export_str()
print(f"🎉 Report generated: {file_path}")

Quick Send

EmailWidget includes a basic email sending function. You can quickly send emails through the EmailSender class, currently supporting QQ Email and NetEase Email.

Before using, you need to obtain the account and key from the respective email providers. Here's a simple example of sending an email by importing QQEmailSender and configuring the account and key:

from email_widget import Email, QQEmailSender

email = Email("Test Email")
email.add_card("Test Card", "This is test card content.")
email.add_quote("This is a quote text.", "PythonImporter")
email.add_status_items(
    [{"label": "Status1", "value": "Complete"}, {"label": "Status2", "value": "In Progress"}],
    title="Test Status",
)
email.add_table_from_data(
    [["Column1", "Column2"], ["Data1", "Data2"]],
    title="Test Table",
)
QQEmailSender(username="your_email@qq.com", password="your_key").send(email)
print("Email sent successfully!")

🔧 Component Showcase

Below are displays of all currently available components (some features may not be updated timely, please refer to documentation if there are errors or inconsistencies):

Actual Display in Email

Desktop Web Version

Mobile Version

🎨 Advanced Features

🎯 Method Chaining Support

# Fluent API design
email = (Email("Project Progress Report")
         .set_subtitle("Q1 Summary")
         .set_footer("Generated by EmailWidget")
         .add_widget(TextWidget().set_content("Overview").set_type(TextType.TITLE_LARGE))
         .add_widget(ProgressWidget().set_value(78).set_label("Overall Progress")))

📚 Learning Resources

🤝 Community & Contributing

🌟 Participate in Open Source

# Clone project
git clone https://github.com/271374667/EmailWidget.git

# Install development dependencies
pip install -e ".[dev]"

# Run tests
pytest tests/

# Submit code
git add .
git commit -m "feat: add new feature"

📞 Contact Us

• 🐛 Bug Reports: GitHub Issues
• 💬 Discussion: GitHub Discussions
• 📧 Email: 271374667@qq.com
• 📺 Video Tutorials: Bilibili Channel

📄 License

This project is licensed under the MIT License.