emailbuilder 0.1.0

Simple HTML e-mail generator

EMailBuilder

Simple HTML e-mail template builder python library. Allows for embedded images and matplotlib charts.

Table of Contens

• EMailBuilder
  • Table of Contens
  • Installation
  • Usage
  • The EMail Class/Object
    • Attributes
      • Subject
      • Sender
      • Receiver
      • Style
    • Methods
      • email.append(component)
      • email.attach(item, mime, type, extension, cid)
      • email.html()
      • email.plain() (W.I.P.)
      • email.message()
      • email.mime() (W.I.P.)
  • Components
    • Basic Elements
      • Header
      • Paragraph
    • Embedabbles
      • Image
      • ImageRaw
      • Figure
    • Containers
      • Container
  • To-Do

 

---

Installation

You can install it with pip:

pip install emailbuilder

 

---

Usage

Import EmailBuilder:

import emailbuilder as eb

Create an emailbuilder.EMail object and append elements to it:

# Create eb.EMail object
# (see the "EMail class" section for more details)
email = eb.EMail(
    "EMail Subject",
    "[e-mail]",
    "[e-mail]"
)

#  Append components to the eb.EMail object
# (see the "Components" section for more details)
email.append(eb.Header("Hello World!"))
email.append(eb.Paragraph("Lorem ipsum dolor sit amet consectetur"))

You can also append matplotlib figures:

plt.figure()
plt.plot([1, 2])
plt.title("Example")

email.append(eb.Figure(plt.gcf(), "example-figure"))

Then, you can send the e-mail via your preferred method. For instance:

s = smtplib.SMTP(...)

...

s.send_message(email.message())
s.quit()

 

---

The EMail Class/Object

This object is used for setting the information relating to the e-mail, and provides methods to render the e-mail contents.

 

Attributes

 

Subject

The e-mail's subject, as a string

 

Sender

The sender's e-mail, as a string

 

Receiver

The receiver(s)'s e-mail(s), as either a string or a list

 

Style

A dictionary containing the basic style rules for the e-mail. (More information concerning styling to be added)

 

Methods

 

email.append(component)

Appends a component to the end of the e-mail

 

email.attach(item, mime, type, extension, cid)

Adds an attachment to the e-mail.

 

email.html()

Returns the e-mail as HTML.

 

email.plain() (W.I.P.)

Returns the e-mail as plain text.

 

email.message()

Returns the e-mail as a EmailMessage object.

 

email.mime() (W.I.P.)

Returns the e-mail as a MIMEMultipart object, for legacy purposes. (May be deprecated in the future.)

 

---

Components

Below are the included components in the emailbuilder library.

 

Basic Elements

 

Header

eb.Header(
    content: str,
    style: dict = {}
)

An <h1> element, with the text from the content parameter.

 

Paragraph

eb.Paragraph(
    content: str,
    style: dict = {}
)

A single paragraph, with the text from the content parameter.

 

Embedabbles

 

Image

eb.Image(
    src: str,
    alt: str = "",
    cid: str = <file name>,
    style: dict = {}
)

An embedded image, loaded from the src path. Alternative text, used for text-only e-mails is passed through the alt parameter.

 

ImageRaw

eb.ImageRaw(
    image: bytes,
    extension: str,
    alt: str = "",
    cid: str = <hashed bytes>,
    style: dict = {}
)

An embedded image, loaded as bytes from the image parameter. An image format must be provided through the extension parameter.

 

Figure

eb.Figure(
    figure: matplotlib figure,
    alt: str,
    style: dict = {},
    kwargs: dict = {}
)

An embedded MatPlotLib figure. Custom arguments for the savefig function can be passed through the kwargs parameter.

 

Containers

 

Container

eb.Container(
    style: dict = {}
)

A <div> element. Items can be appended with the append(item) method, just like with the EMail object.

 

---

To-Do

• Write basic usage guide
• Add table components
• Document style argument
• Improve plain text function