manokit 1.1.1

An easy-to-use, purely native email sender

Table of contents

• Introduction
• Installation
• Package overview
• Simple Emails
  • SimpleEmail code examples
• Emails with HTML
  • HTMLEmail code examples
• Similarity is key

Introduction

Manokit is an easy-to-use native email sender for Python. That's right! There is no dependencies!

With just a few lines of code you will be able to send fancy emails with no headache in sight!

Installation

You can install this package directly from PyPI or using pip:

pip install manokit

Also you can download installation-ready archives and project's source code from the Releases page.

Package overview

Manokit consists of 2 modules: manokit.email provides all the functionality needed to send emails fast and simple and manokit.exceptions contains all custom exceptions that can be raised by this package in case something goes wrong.

Here's a each module's struncture

• manokit.email module:

  • SimpleEmail class for sending plain-text emails
  • HTMLEmail class for sending emails containing HTML
  • BaseEmail class for development and expansion purposes

• manokit.exceptions module:

  • NotAValidEmailAddressError - sender's or recepient's email address is not valid (it may be a typo, missing domain, etc)
  • AttachmentError - there's an error with email's attachment file. It may point that file does not exist, is not a file or cannot be accessed.
  • BodyError - there's a problem with email's body. It may contain 'bad' characters, etc.
  • ParameterError - one or more of function's parameters are invalid. They can be of wrong type, have 'bad' values, etc
  • AuthError - there's a problem during authentication. It may indicate bad credentials or that mail server is restricting connections from an unverified source (like GMail does)
  • SMTPError - there sre some problems with SMTP connection. It may indicate faulty SMTP server, unsupported type of connection, etc.
  • EmailError - email cannot be sent. It is caused by missing metadata (subject, recepients, body, ...)

Simple Emails

To send a very simple plain-text email you need to import SimpleEmail class from manokit.email module.

To initialize it, you need to pass 4 things: an SMTP server address, its port, your credentials and enable SSL (optional).

It looks like this (e.g. send an email via GMail):

from manokit.email import SimpleEmail

op = SimpleEmail('smtp.gmail.com', 465, ('[e-mail]', 'TotallySecure1'), True)

It'll automatically authenticate you.

Note that this class does not support email with HTML in any way and will raise an exception if it detects it. The reason is that HTMLEmail class is designed to work with HTML and therefore is more optimized. Simply put, SimpleEmail is just not designed for HTML.

A bit of clarification. Near class' properties you can see two different specifiers: '(property)' means that you cannot change this property after instance creation; '(property + setter)' means that you can change this property's value by this expression:

op.property_name = <your_value>

Here's a complete list of class' methods and properties:

• SimpleEmail

  • subject (property + setter) Email's subject line. By default it is None.
  • timestamp (property) Email's time of birth, basically. It indicates exact time when class' instance was created and is used as email's time metadata
  • filesize_limit (property) Maximum attachment's filesize. It is equal to 20 Mb because this is the most common limit. If file is larger, an AttachmentError exception is raised. This limit cannot be disabled.
  • body (property + setter) Email's body. By default it is None. Note: if there are any HTML tags, a BodyError exception will be raised
  • recepients (property + setter) Addressed who will receive this email. This can take form of a single string or a list of strings. All emails are checked for validity and a NotAValidEmailAddressError exception is raised if one of emails is not valid.
  • attachments (property + setter) Email's attachments. You can specify an unlimited number of files to attach in form of a list of their path. They can be relative because manokit automatically converts them to absolute.
  • sender_email (property) Sender's Email address.
  • send() -> None (method) Sends an email. Simple as that. It takes all the parameters from properties specified above and does all the dirty work, like setting headers, behind the scenes.
  • body_from_file(file: str) -> None (method) Reads file's contents and uses it as email's body. File: str - path to file If HTML tags are detected in file's contents, an exception will be raised.

SimpleEmail code examples

Sendind a very basic email:

from manokit.email import SimpleEmail

# Initializing
op = SimpleEmail('smtp.gmail.com', 465, ('[e-mail]', 'MyPasswd1'), True)

# Setting all the important parts
# By the way, you can change any of these parameters at any time
op.subject = 'A very basic email with Manokit'
op.body = "This is a very basic letter sent to you via Manokit"
op.recepients = ['[e-mail]', '[e-mail]']

# Sending email
op.send()

Sending a basic email with attachments:

from manokit.email import SimpleEmail

# Initializing
op = SimpleEmail('smtp.gmail.com', 465, ('[e-mail]', 'MyPasswd1'), True)

# Setting all the necessary parameters
op.subject = 'Quaterly Report'
op.body = "Here's the quaterly report for Q1 2021. Sending in PDF and DOCX formats"
op.recepients = '[e-mail]'

# Adding attachments
op.attachments = ['./report.pdf', './report.docx']

# Sending email
op.send()

Reading email's body from file

from manokit.email import SimpleEmail

# Initializing
op = SimpleEmail('smtp.gmail.com', 465, ('[e-mail]', 'MyPasswd1'), True)

# Setting all the necessary parameters
op.subject = 'A Screenplay Draft'
op.body_from_file('./screenplay/draft.txt')
op.recepients = '[e-mail]'

# Sending email
op.send()

Emails with HTML

To send fancy emails you'll need to use HTMLEmail class from manokit.email module.

This class lets you use HTML and inline styling to make boring text very engaging.

To initialize it, you need to pass 4 things: an SMTP server address, its port, your credentials and enable SSL (optional).

It is very similar to SimpleEmail.

from manokit.email import HTMLEmail

op = HTMLEmail('smtp.gmail.com', 465, ('[e-mail]', 'TotallySecure1'), True)

Here's a complete list of class' methods and properties:

• HTMLEmail

  • subject (property + setter) Email's subject line. By default it is None.
  • timestamp (property) Email's time of birth, basically. It indicates exact time when class' instance was created and is used as email's time metadata
  • filesize_limit (property) Maximum attachment's filesize. It is equal to 20 Mb because this is the most common limit. If file is larger, an AttachmentError exception is raised. This limit cannot be disabled.
  • body (property + setter) Email's body. By default it is None. Note: if there are no HTML tags present in the body, default styling is applied. It changes font family to Verdana and text color to #262626
  • recepients (property + setter) Addressed who will receive this email. This can take form of a single string or a list of strings. All emails are checked for validity and a NotAValidEmailAddressError exception is raised if one of emails is not valid.
  • attachments (property + setter) Email's attachments. You can specify an unlimited number of files to attach in form of a list of their path. They can be relative because manokit automatically converts them to absolute.
  • sender_email (property) Sender's Email address.
  • send() -> None (method) Sends an email. Simple as that. It takes all the parameters from properties specified above and does all the dirty work, like setting headers, behind the scenes.
  • body_from_file(file: str) -> None (method) Reads file's contents and uses it as email's body. File: str - path to file If no HTML tags are found, default styling is applied.

HTMLEmail code examples

Sendind a simple HTML email:

from manokit.email import HTMLEmail

# Initializing
op = HTMLEmail('smtp.gmail.com', 465, ('[e-mail]', 'MyPasswd1'), True)

# Setting all the important parts
op.subject = 'A HTML Email with Manokit'
# HTML can be partial (without <html> and <body> tags)
op.body = """\
    <div>
        <span style="color: pink;">Here you can put basically anything</span>
    </div>
    <a href='https://github.com/NickolaiBeloguzov/manokit'>Manokit is awesome</a>
"""
op.recepients = ['[e-mail]', '[e-mail]']

# Sending email
op.send()

Sending a HTML email with attachments:

from manokit.email import HTMLEmail

# Initializing
op = HTMLEmail('smtp.gmail.com', 465, ('[e-mail]', 'MyPasswd1'), True)

# Setting all the necessary parameters
op.subject = 'Website patch (final)'
op.body = """\
    <div id="files">
        Here are all my files I'm sending you:
        <ul>
            <li>template.html - A site template</li>
            <li>template.css - Styles for the template</li>
            <li>main.js - Main template script</li>
        </ul>

        <span style="color: red; font-weight: bold;">
            These files must be in the same folder
        </span>
    </div>
    """
op.recepients = '[e-mail]'

# Adding attachments
op.attachments = ['./site/template.html', './site/template.css', './site/main.js']

# Sending email
op.send()

Reading email's body from file

from manokit.email import HTMLEmail

# Initializing
op = HTMLEmail('smtp.gmail.com', 465, ('[e-mail]', 'MyPasswd1'), True)

# Setting all the necessary parameters
op.subject = 'Your subscription has ended!'
op.body_from_file('./email-templates/sub-end.html')
op.recepients = '[e-mail]'

# Sending email
op.send()

Similarity is key

You might've noticed that SimpleEmail and HTMLEmail are very similar in terms of used methods and their general implication. This similarity exists because all these classes are based on top of one main BaseEmail class that actually contains all the functionality.

That opens up new doors for YOU! Yes! With Manokit you can build your own better email sending libraries. Simply inherit the BaseEmail class and go beyond anyone's expectations

Here's how it works:

from manokit.email import BaseEmail

class BetterEmail(BaseEmail):
    def __init__(self, host, port, creds, ssl, **kwargs) -> None:
        # do your own super cool stuff
        super().__init__(host, port, creds, ssl)

    # Override superclass methods to be better
    def send() -> None:
        print('Sending emails to {recs}..'.format(recs=', '.join(self._recepients))

        # Even more super cool stuff

        super().send()

Got questions or ideas?

That's great. This means that this project is alive.

You can start by opening a Pull Request and describe your problem/suggestion/idea there.

For now that's all! But not for long...