Skip to content
Library for sending/reading email messages by using the IMAP and SMTP protocols
Branch: master
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Type Name Latest commit message Commit time
Failed to load latest commit information.


Emailpy is a basic python library for sending and reading email messages by using the IMAP and SMTP protocols. It's meant to offer a fast and painless access to email services. Supported Python2 and Python3.


  • Send/read messages via IMAP and SMTP
  • Attach and download files to/from messages
  • Easily add custom email services
  • Ease of use


Get emailpy source from Github and install it.


Execute the following commands:

git clone git://
cd emailpy/
sudo python emailpy/ install
sudo rm -rf emailpy


Download repository or execute the following git command:

git clone git://

Via Windows cmd (or Powershell) navigate to the downloaded folder emailpy/ and execute the follwing command:

python emailpy/ install

Finally, delete the folder emailpy/

How to use emailpy

In your code, import emailpy and get a reference to a Service (e.g. Gmail) :

import emailpy

sm = emailpy.ServiceManager()
mail = sm.get_service("gmail")

then setup with user id and password:

mail.setup("", "password")

At the same way, it is possible to get other services:

mail1 = sm.get_service("outlook")
mail2 = sm.get_service("yahoo")

Note: at the moment they are handled the following services: gmail, yahoo, outlook. More coming in the future. To use other services, please read the Custom Email Services section.

Send/Read messages

Send message:

mail.send(["", ""], "Subject", body="Message body" )

The body parameter is optional and can be omitted. Messages can be read by calling the method and iterating the returned messages:

messages =
for msg in messages:
    print("Date: " + str(msg.Date))
    print("From: " + msg.From)
    print("To: " + msg.To)
    print("Subject: " + msg.Subject)

In the same way, it is possible to iterate the parts of message body:

messages =
for msg in messages:
    for b in msg.Body:
        print("Content part: " + str(b))

Function can take search criteria as argument. Criteria values can be accessed via the emailpy.Constants :

from emailpy import Constants
messages =

For example, filtering by 'From' field:

messages = + ' "joey smith"')

Or filtering by date:

messages = + ' 10-Aug-2019')

For more information about IMAP search criterias, please take a look at IMAP.


Sending attachment:

mail.send([""], "Subject", attachments = ["file1.txt", "file2.bat"] )

pass the files' paths into the attachments argument. Attachments of the result messages can be downloaded by using the following argument: True)

attachments will be stored under the ./attachment/ subfolder. It is possible to explore attachments' filenames for each message:

for msg in, download_attachments=True):
    for fn in msg.Attachments:
        print("Attachment file name: " + fn)

Please note that EMessage.Attachments contains only the names of the possible attachments, even if the download_attachments is False.

Custom Email Services

You can configure a custom Email server by creating a custom .xml service file (similar to services.xml). Example:

<config version="0">
        <service id="custom_service" smtp_address="smtp.custom" smtp_port="123" imap_address="imap.custom" imap_port="321" />

then, pass its path to the ServiceManager:

my_sm = ServiceManager("my_service_file.xml")
custom_service = my_sm.get_service("custom_service")

It is important to avoid duplicate Services IDs in the .xml file.

Another (faster) way to use custom email service is to use directly the EmailService class:

my_sm = MailService("gmail", "", 587, "", 993)

Account security

In order to grant IMAP and SMTP access to your program with services (e.g. Gmail, Yahoo) you may need to lower the security of the account in order to permit access from third-party applications.


This project is incomplete and some features may miss. Feel free to make your modifications and improvements by forking the master branch


Copyright(c) 2019 Sebastiano Campisi - Read LICENSE file for more details.

You can’t perform that action at this time.