Installation

Install Mayil using pip:

pip install mayil

Dependencies:

  • pandas==1.5.3
  • jinja2==3.1.2
  • premailer==3.10.0
  • markdown2==2.4.12 (required for markdown support)

Quick Start

Here's a simple example to get you started:

# Import Mayil
from mayil import Mayil
my = Mayil()

# Create a simple email
my.title("Welcome to Mayil")
my.text("This is a simple email created with Mayil.")

# Optional: Save to file
my.save("welcome.html")

API Reference

Mayil provides a variety of methods to create beautiful HTML emails:

title(text, center=False)

Add a title to the email body.

Parameters:
text (str): The title text
center (bool): Whether to center the title. Defaults to False.
my.title("Welcome to Our Newsletter", center=True)

Welcome to Our Newsletter

subheader(text)

Add a subheader to the email body.

Parameters:
text (str): The subheader text
my.subheader("Product Updates")

Product Updates

text(text, justify=False, italic=False, bold=False, underline=False, font_size=None)

Add text to the email body.

Parameters:
text (str): The text content
justify (bool): Whether to justify the text. Defaults to False.
italic (bool): Whether to italicize the text. Defaults to False.
bold (bool): Whether to bold the text. Defaults to False.
underline (bool): Whether to underline the text. Defaults to False.
font_size (int): Custom font size in pixels. Defaults to None.
# Basic text
my.text("This is a regular paragraph.")

# Styled text
my.text("This is bold and italic text.", bold=True, italic=True)

# Custom sized text
my.text("This is larger text.", font_size=20)

This is a regular paragraph.

This is bold and italic text.

This is larger text.

caption(text, italic=False)

Add a caption text with smaller font size and lighter color.

Parameters:
text (str): The caption text
italic (bool): Whether to italicize the text. Defaults to False.
# Regular caption
my.caption("Figure 1: Data visualization")

# Italic caption
my.caption("Source: Company annual report", italic=True)

Figure 1: Data visualization

Source: Company annual report

metric(label, value, color="#000000")

Add a metric display with label and value.

Parameters:
label (str): The metric label
value (str): The metric value
color (str): The color of the value. Defaults to black.
my.metric("Active Users", "1,234", color="#88C0D0")
Active Users
1,234

sticky_note(title, text, color="yellow", justify=False)

Add a sticky note component with title and text.

Parameters:
title (str): Title text for the sticky note
text (str): Main text content
color (str): Color of sticky note. Defaults to "yellow".
justify (bool): Whether to justify the text. Defaults to False.
my.sticky_note("Important Notice", "Please read this carefully.", color="blue")
Important Notice
Please read this carefully.

divider()

Add a light grey dotted divider line.

from mayil import Mayil
my = Mayil()

my.divider()

break_space(height=20)

Add a vertical white space break to create spacing between elements.

Parameters:
height (int): Height of the break in pixels. Defaults to 20.
from mayil import Mayil
my = Mayil()

# Default break (20px)
my.break_space()

# Custom height break
my.break_space(height=50)
Default break (20px)
Custom break (50px)

columns(n_cols)

Create a specified number of columns for horizontal layout.

Parameters:
n_cols (int): Number of columns (max 4)
cols = my.columns(3)
with cols[0]:
    my.metric("Metric 1", "100")
with cols[1]:
    my.metric("Metric 2", "200")
Metric 1
100
Metric 2
200
Metric 3
300

dataframe(df, align='left', use_container_width=True)

Add a styled DataFrame to the email.

Parameters:
df: pandas DataFrame to display
align (str): Alignment of table content - 'left', 'center', or 'right'
use_container_width (bool): Whether the table should take up the full container width (true) or auto-size to fit content (false). Defaults to True.
# Import required libraries
from mayil import Mayil
import pandas as pd

my = Mayil()

# Create sample DataFrame
df = pd.DataFrame({
    'Name': ['John', 'Jane', 'Bob'],
    'Score': [85, 92, 78]
})

# Full width table (default)
my.dataframe(df)

# Auto-sized width table (only as wide as needed)
my.dataframe(df, align='center', use_container_width=False)

Full width table:

Name Score
John 85
Jane 92
Bob 78

Auto-sized table (use_container_width=False):

Name Score
John 85
Jane 92
Bob 78

ftable(df, conditions=None, cell_colors=None, text_colors=None, align='left', use_container_width=True)

Add a formatted table with conditional coloring based on column values.

Parameters:
df (pandas.DataFrame): The dataframe to display
conditions (dict): Dictionary mapping column names to list of conditions
cell_colors (dict): Dictionary with column names and conditions for cell background colors
text_colors (dict): Dictionary with column names and conditions for text colors
align (str): Text alignment - 'left', 'center', or 'right'
use_container_width (bool): Whether the table should take up the full container width (true) or auto-size to fit content (false). Defaults to True.
# Import required libraries
from mayil import Mayil
import pandas as pd

my = Mayil()

# Create sample DataFrame
df = pd.DataFrame({
    'Name': ['John', 'Jane', 'Bob'],
    'Score': [85, 92, 78],
    'Active': [True, False, True]
})

# Define conditions for formatting
conditions = {
    'Score': [
        (lambda x: x < 90, '#ff0000'), # Red if < 90
        (lambda x: x >= 90, '#00ff00') # Green if >= 90
    ],
    'Active': [
        (lambda x: x == True, '#00ff00'), # Green if True
        (lambda x: x == False, 'blue') # Blue if False
    ]
}

# Full width table with cell background colors
my.ftable(df, cell_colors=conditions)

# Auto-sized table with text colors
my.ftable(df, text_colors=conditions, use_container_width=False)

Full width table with cell background colors:

Name Score Active
John 85 True
Jane 92 False
Bob 78 True

Auto-sized table with text colors (use_container_width=False):

Name Score Active
John 85 True
Jane 92 False
Bob 78 True

plotly_chart(fig)

Add an interactive Plotly chart to the email.

Parameters:
fig (plotly.graph_objects.Figure): The Plotly figure to display
# Import required libraries
from mayil import Mayil
import plotly.express as px

my = Mayil()

# Create sample data and plot
df = px.data.stocks()
fig = px.line(df, x='date', y='GOOG')

# Add chart to email
my.plotly_chart(fig)
Trend Analysis
22
18
15
12
10
Jan 1
Jan 3
Jan 5
Jan 7
Jan 9
Date: Jan 5, 2024
Value: 19

markdown(text)

Convert markdown text to HTML and add it to the email body. Requires the markdown2 package.

Parameters:
text (str): The markdown formatted text
# Import Mayil
from mayil import Mayil
my = Mayil()

# Basic markdown example
my.markdown(""" # Heading 1 ## Heading 2 - List item 1 - List item 2 **Bold text** and *italic text* ```python def hello(): print('Hello, World!') ``` """)

Heading 1

Heading 2

  • List item 1
  • List item 2

Bold text and italic text

def hello():
    print('Hello, World!')

mention(emails, color=None)

Add @mentions with email addresses in colorful rounded boxes. Creates visually appealing mention tags for email addresses.

Parameters:
emails (list): List of email addresses to mention
color (str, optional): Hex color code to use for all mentions. If not provided, random neon colors will be used.
# Import Mayil
from mayil import Mayil
my = Mayil()

# Basic mentions with random colors
my.mention(["john@example.com", "jane@example.com"])

# Mentions with custom color
my.mention(
    ["support@example.com", "sales@example.com"],
    color="#0070F3"
)
@john@example.com @jane@example.com
@support@example.com @sales@example.com

image(source, alt_text=None, width=None, height=None)

Add an image to the email body. Supports local files, URLs, and base64 encoded images.

Parameters:
source (str): Path to local image file, URL to image, or base64 encoded image data
alt_text (str, optional): Alternative text for the image
width (str/int, optional): Width of the image (e.g., "100%", 500)
height (str/int, optional): Height of the image (e.g., "auto", 300)
# Import Mayil
from mayil import Mayil
my = Mayil()

# Local image file
my.image("path/to/image.jpg", alt_text="Company Logo")

# Image from URL
my.image(
    "https://example.com/image.png",
    width="100%",
    height="auto"
)

# Base64 encoded image
my.image(
    "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgA...",
    width=300
)
Sample Image

Images are automatically optimized and embedded in the email

signature(salutation="Best regards,", name=None, designation=None, signature_image=None)

Add a professional email signature at the end of the email. Supports text-based signatures and image signatures (including SVG).

Parameters:
salutation (str, optional): The salutation to use. Defaults to "Best regards,"
name (str, optional): The name to display in the signature
designation (str, optional): The designation/title/position to display under the name
signature_image (str, optional): Path to signature image file (jpg/png) or SVG content, or URL to image
# Import Mayil
from mayil import Mayil
my = Mayil()

# Basic text signature
my.signature("Best regards,", "John Doe", "Senior Software Engineer")

# With image signature (local file)
my.signature(
    name="John Doe",
    designation="Senior Software Engineer",
    signature_image="path/to/signature.png"
)

# With SVG signature
my.signature(
    name="John Doe",
    signature_image='''<svg width="200" height="40">...</svg>'''
)

# With image URL
my.signature(
    signature_image="https://example.com/signature.jpg"
)

Best regards,

John Doe

Senior Software Engineer

John Doe

show()

Preview the email body in the default web browser. Opens the current email body content directly in a new browser tab.

Returns:
None
# Import Mayil
from mayil import Mayil
my = Mayil()

# Create email content
my.title("Welcome")
my.text("Hello, World!")

# Preview in browser
my.show()
Opens preview in your default web browser