epirus / zmail

Zmail allows you to send and get emails as possible as it can be in python.

zmail

中文介绍请戳这里

Introduction

Zmail allows you to send and get emails as possible as it can be in python.There is no need to check server address or make your own MIME object.With zmail, you only need to care about your mail content.

Installation

Zmail only running in python3 without third-party modules required. Do not support python2.

Option 1:Install via pip（Better）

$ pip3 install zmail

or

$ pip install zmail

If that means your pip is also working for python3.

Option 2:Download from Github

You can download the master branch of zmail,unzip it ,and do

$ python3 setup.py install

Features

• Automatic looks for server address and it's port.
• Automatic use suitable protocol to login.
• Automatic converts a python dictionary to MIME object(with attachments).
• Automatic add mail header and local name to avoid server reject your mail.
• Easily custom your mail header.
• Support HTML as mail content.
• Only require python >= 3.5 , you can embed it in your project without other module required.

Usage

Before using it, please ensure:

• Using python3
• Open SMTP/POP3 function in your mail (For @163.com and @gmail.com you need to set your app private password)

Then, all you need to do is just import zmail.

Examples

Send your mail

import zmail
mail = {
    'subject': 'Success!',  # Anything you want.
    'content': 'This message from zmail!',  # Anything you want.
    'attachments': '/Users/zyh/Documents/example.zip',  # Absolute path will be better.
}

server = zmail.server('[e-mail]‘, 'yourpassword')

server.send_mail('[e-mail]', mail)

• To a list of recipients

server.send_mail(['[e-mail]','[e-mail]'], mail)

• Send HTML content

mail = {
    'subject': 'Success!',  # Anything you want.
    'content_html': zmail.get_html('/Users/example.html'), # Absolute path will be better.
    'attachments': '/Users/zyh/Documents/example.zip',  # Absolute path will be better.
}
server.send_mail('[e-mail]',mail)

OR

with open('/Users/example.html','r') as f:
    content_html = f.read()
mail = {
    'subject': 'Success!',  # Anything you want.
    'content_html': content_html, 
    'attachments': '/Users/zyh/Documents/example.zip',  # Absolute path will be better.
}
server.send_mail('[e-mail]',mail)

Retrieve your mail

• Get the latest mail.

import zmail
server = zmail.server('[e-mail]‘, 'yourpassword')
mail = server.get_latest()

• Retrieve mail by its id.

mail = server.get_mail(2)

• Get a list of mails by its (subject,after,before,sender)

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

In the example, if 'GitHub' is in mail's subject, it will be matched, such as ' [GitHub] Your password has changed'

sender is the same way.

• Get all mails' info, include each mail's header.A list of dictionary, each dictionary include all headers can be extracted.

mail_info = server.get_info()

• Get mailbox info.

mailbox_info = server.stat()

The result is a tuple of 2 integers: (message count, mailbox size).

Parse your mail

In zmail, all mails will be mapped to a python dictionary, you can access your mail by

subject = mail['subject']

Show you mail, use zmail.show()

import zmail
server = zmail.server('[e-mail]’, 'yourpassword')
mail = server.get_latest()
zmail.show(mail)

Output, example :

content-type multipart/mixed
subject Success!
to zmail_user
from zmail<[e-mail]>
date 2018-2-3 01:42:29 +0800
boundary ===============9196441298519098157==
content ['This message from zmail!']
contents [[b'Content-Type: text/plain; charset="utf-8"', b'MIME-Version: 1.0', b'Content-Transfer-Encoding: base64', b'', b'VGhpcyBtZXNzYWdlIGZyb20gem1haWwh', b'']]
attachments None
id 5

Mail structure

• content-type: Mail content type
• subject: Mail subject
• to
• from
• date: year-month-day time TimeZone
• boundary: If mail is multiple parts, you can get the boundary
• content: Mail content as text/plain
• contents: Mail's body as bytes,divided by boundary
• attachments: None or [['attachment-name;Encoding','ATTACHMENT-DATA']...]
• id: Mailbox id

Get attachment

import zmail
server = zmail.server('[e-mail]‘, 'yourpassword')
mail = server.get_latest()
zmail.get_attachment(mail)

you can rename your attachment file, by

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

Supported mail server

The mail server in this list has been tested and approved.

If your mail server not in it, don't worry, zmail will handle it automatically.If there any problems in use, pls tell me in the Github.

Server address	Send mail	Retrieve mail	Remarks
@163.com	✓	✓	Need app private password
@qq.com	✓	✓	POP3 need app private password
@126.com	✓	✓
@yeah.net	✓	✓
@gmail.com	✓	✓	Need app private password
@sina.com	✓	✓
@outlook	✓	✓

API

server = zmail.server('user@example','password')

SMTP

• server.send_mail([recipient,], mail)

POP3

• server.get_mail(which)
• server.get_mails(subject, sender, after, before)
• server.get_latest()
• server.get_info()
• server.stat()

Parse mail

• server.get_attachment(mail)

Mail

• subject
• content
• content_html
• from
• to

Other

• zmail.show()