Simplify Python Email Sending with zmail: A Complete Guide

Introduction

Sending emails is a simple requirement, but many pitfalls still exist in practice; the zmail project was created to make sending emails with Python as easy as possible.

Drawbacks of Other Libraries

Server rejection due to improperly defined headers (From, To, etc.) and provider‑specific checks.

Complex construction, especially when adding attachments.

Sending difficulties: finding SMTP server, port, SSL/TLS requirements.

Parsing challenges: handling bytes, boundaries, and encoding.

Excessive external dependencies causing version conflicts.

Advantages of zmail

Automatically fills most headers that cause server rejections.

Maps a dictionary to an email, making construction as simple as building a dict.

Auto‑detects mail service provider address and port, selects appropriate protocol.

Depends only on Python 3; easy to embed in other projects.

Use Cases

Monitoring scripts for sending/receiving emails.

Embedding email functionality into existing projects.

Custom email sending processes such as scheduled or timed deliveries.

Installation

Install via pip: pip3 install zmail zmail supports only Python 3; ensure SMTP is enabled for your email accounts.

Sending Email

Example code:

import zmail

mail_content = {

'subject': 'Success!',

'content': 'This message from zmail!',

}

server = zmail.server('[email protected]', 'your_password')

server.send_mail('[email protected]', mail_content)

To add attachments, include an 'attachments' key with the file path.

Receiving Email

Retrieve the latest email:

import zmail

server = zmail.server('[email protected]', 'yourpassword')

mail = server.get_latest()

Retrieve by ID: mail = server.get_mail(2) Search by criteria:

mail = server.get_mails(subject='GitHub', after='2018-1-1', sender='github')

Parsing Email

Emails are returned as dictionaries; access fields like: subject = mail['subject'] Display the email:

zmail.show(mail)

Email Structure

content-type

subject

to

from

date

boundary (for multipart)

content (plain text)

contents (body parts)

attachments

id (mailbox ID)

Attachments

Get attachments: zmail.get_attachment(mail) Rename attachment when saving:

zmail.get_attachment(mail, 'example.zip')

Supported Email Providers

The following providers have been tested and work with zmail: