Zmail is a Python library designed to simplify the process of sending emails. It addresses common pain points associated with traditional email sending methods, such as complex MIME construction, server configuration issues, and dealing with various authentication protocols.

Traditional approaches often involve manually constructing email headers and MIME structures, which can lead to server rejections due to improper formatting. Configuring the correct SMTP server, port, and security protocol (SSL/TLS) for each email provider can be cumbersome. Furthermore, many libraries introduce unnecessary dependencies that might conflict with existing project packages.

Zmail offfers a streamlined solution with the following key advantages:

Automatic Header Management: Automatically populates essential headers to prevent common server rejection issues. Dictionary-Based Construction: Email content is defined using a simple dictionary, making the process intuitive and less error-prone. Auto-Configuration: Automatically detects the appropriate SMTP server, port, and protocol for supported email providers. Lightweight Dependency: Zmail has a single dependency on Python 3, ensuring easy integration into any project.

You can use Zmail for various purposes, including:

As a notification module in monitoring scripts. Integrating email functionality into existing applications. Implementing custom sending logic, such as scheduled or timed email dispatches.

Installation

Zmail can be installed via pip:

pip install zmail

Note: Zmail is compatible with Python 3 and does not support Python 2.

Basic Usage Examples

Before using Zmail, ensure that SMTP access is enabled for your email account. For services like Gmail or 163.com, you may need to generate a specific app password.

Sending a Simple Email

The core of Zmail's functionality is its ability to send emails using a dictionary to define the message content.

import zmail

# Define the email's content and subject in a dictionary
email_payload = {
    'subject': 'Hello from Zmail!',
    'content_text': 'This is a test message sent using the Zmail library. It's very straightforward.'
}

# Initialize the mail server with your credentials
mail_server = zmail.server('your_email@example.com', 'your_password')

# Send the email to a single recipient
mail_server.send_mail('recipient@example.com', email_payload)

Adding Attachments

Including attachments is as simple as adding a list of file paths to the email payload dictionary.

# Add attachments to the existing email payload
email_payload['attachments'] = ['/path/to/document.pdf', '/path/to/image.png']

Sending to Multiple Recipients

You can send a single email to multiple recipients by providing a list of email addresses.

# Define a list of recipients
recipient_list = ['user1@example.com', 'user2@example.com']

# Send the email to all recipients in the list
mail_server.send_mail(recipient_list, email_payload)

Custom Headers

Additional email headers can be included directly in the payload dictionary.

# Add custom headers
email_payload['headers'] = {
    'X-Custom-Header': 'MyValue',
    'Reply-To': 'support@example.com'
}

Supported Email Providers

Zmail supports a wide range of popular email providers, including but not limited to:

Gmail (@gmail.com) QQ Mail (@qq.com) 163 Mail (@163.com) Sina Mail (@sina.com) 126 Mail (@126.com)

While Zmail has been tested with many providers, it is designed to be flexible and should work with most standard SMTP servers.