Installation
Install Mayil using pip:
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:
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.
Welcome to Our Newsletter
header(text)
Add a header to the email body.
Latest Updates
subheader(text)
Add a subheader to the email body.
Product Updates
text(text, justify=False, italic=False, bold=False, underline=False, font_size=None)
Add text to the email body.
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.
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.
sticky_note(title, text, color="yellow", justify=False)
Add a sticky note component with title and text.
divider()
Add a light grey dotted divider line.
my = Mayil()
my.divider()
break_space(height=20)
Add a vertical white space break to create spacing between elements.
my = Mayil()
# Default break (20px)
my.break_space()
# Custom height break
my.break_space(height=50)
columns(n_cols)
Create a specified number of columns for horizontal layout.
with cols[0]:
my.metric("Metric 1", "100")
with cols[1]:
my.metric("Metric 2", "200")
dataframe(df, align='left', use_container_width=True)
Add a styled DataFrame to the email.
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:
Auto-sized table (use_container_width=False):
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.
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:
Auto-sized table with text colors (use_container_width=False):
plotly_chart(fig)
Add an interactive Plotly chart to the email.
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)
hyperlink(text, url)
Add a clickable link to the email.
from mayil import Mayil
my = Mayil()
# Add hyperlink
my.link("Visit our website", "https://example.com")
markdown(text)
Convert markdown text to HTML and add it to the email body. Requires the markdown2 package.
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.
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"
)
image(source, alt_text=None, width=None, height=None)
Add an image to the email body. Supports local files, URLs, and base64 encoded images.
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
)
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).
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
show()
Preview the email body in the default web browser. Opens the current email body content directly in a new browser tab.
from mayil import Mayil
my = Mayil()
# Create email content
my.title("Welcome")
my.text("Hello, World!")
# Preview in browser
my.show()