EMailBuilder

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

Table of Contents

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

---

Installation

You can install the latest release with pip:

pip install emailbuilder

Or build and install the development version yourself:

git clone https://github.com/coheleth/emailbuilder &&\
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",
    "sender@example.com",
    "receiver@example.com"
)

#  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, Copy and Blind Copy

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()

email.append(component)

Appends a component to the end of the e-mail

email.attach()

with open("file.png", "rb") as f:
  email.attach(
      item = f.read(),
      type = "image",
      extension = "png",
      cid = "my_image",
      mime = MIMEImage(f.read()) # Optional
  )

Adds an attachment to the e-mail.

email.html()

print(email.html())

Returns the e-mail as HTML.

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

print(email.plain())

Returns the e-mail as plain text.

email.message()

s.send_message(email.message())

Returns the e-mail as a EmailMessage object.

---

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.

Table

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

A simple table, created from a dictionary of arrays, the keys' names being the columns, and the values, the rows.

Usage with pandas dataframes

If used with pandas dataframes, convert the dataframe to a dictionary with the default 'dict' orientation, eg.:

df = pd.DataFrame({
    'Name': ['Alice', 'Bob'],
    'Age': [25, 30]
})

table = pd.to_dict(orient='dict')

email.append(eb.Table(table))

Usage with other components

Other components, such as eb.Header, can be passed via de dictionary, eg.:

table = {
  'Attribute': ['personality', 'voice'],
  'Alice': ['calm', 'soft'],
  'Bob': ['nervous', eb.Header('LOUD')]
}

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 win32com.client outlook support
• Improve classes and functions documentation
• Add CC and BCC
• Add table component
• Document style argument
• Improve plain text function