Red Mail Documentation

Red Mail is an advanced email sender for Python designed to make complex email tasks trivial. Key capabilities include:

• Rich Content: Easily embed images, plots, and tables directly into the email body.
• Attachments: Attach documents to your emails.
• Templating: Built-in support for Jinja templates and reusable HTML templates.
• Pre-configured Providers: Easy setup for Gmail and Outlook.
• Advanced Routing: Support for cc and bcc recipients.
• Extensibility: Includes a logging handler and a Flask extension.
• Protocol Flexibility: Ability to configure specific SMTP settings.

If you are using a custom SMTP server or need to change the default protocol/port for a provider, you can override the attributes of the sender instance.

By default, Red Mail uses STARTTLS. If your provider requires a different protocol or port, you can manually set:

• sender.port: The port number.
• sender.cls_smtp: The SMTP class/protocol configuration.

Red Mail includes pre-configured sender instances for common email providers to simplify setup. These instances come with the correct host and port pre-set.

Note on Sender Identity: Many providers do not allow you to change the sender address to something different from the credentials used to log in. In such cases, providing a different sender argument to the .send() method may have no effect.

Instead of providing individual SMTP parameters, you can pass an existing EmailSender instance directly to the email argument of EmailHandler or MultiEmailHandler.

Note: Red Mail creates a copy of the EmailSender instance to ensure that setting attributes like subject, sender, or receivers on the handler does not affect the original instance used elsewhere in your application.

from redmail import EmailSender, EmailHandler

hdlr = EmailHandler(
    email=EmailSender(host="localhost", port=0),
    subject="A log record",
    receivers=["me@example.com"],
)

By default, Red Mail opens and closes the SMTP connection for every email sent. For high-volume sending, you should keep the connection open to improve performance. You can do this using a context manager (with email:) or by manually calling .connect() and .close().

# Option 1: Using a context manager (Recommended)
with email:
    email.send(subject='msg 1', sender='me@ex.com', receivers=['a@ex.com'])
    email.send(subject='msg 2', sender='me@ex.com', receivers=['b@ex.com'])

# Option 2: Manual connect/close
try:
    email.connect()
    email.send(subject='msg 1', sender='me@ex.com', receivers=['a@ex.com'])
    email.send(subject='msg 2', sender='me@ex.com', receivers=['b@ex.com'])
finally:
    email.close()

Install the redmail package from PyPI using pip to start using the advanced email sender features.

pip install redmail

Pass a dictionary to the headers parameter in .send() to add or override email headers. This can be used to set custom Importance, Date, or even override standard headers like From, To, Cc, Bcc, Date, and Message-ID.

import datetime

email.send(
    subject='email subject',
    sender="The Sender <me@example.com>",
    receivers=['you@example.com'],
    headers={
        "Importance": "high",
        "Date": datetime.datetime(2021, 1, 31, 6, 56, 46)
    }
)

Use the cc and bcc parameters to include carbon copy and blind carbon copy recipients. You can also use aliases by providing a string in the format "Name <email@example.com>" for both sender and receivers. The alias is displayed to the user, but the actual email address is still usable.

# CC and BCC
email.send(
    subject='email subject',
    sender="me@example.com",
    receivers=['you@example.com'],
    cc=['also@example.com'],
    bcc=['outsider@example.com']
)

# Using Aliases
email.send(
    subject='email subject',
    sender="The Sender <me@example.com>",
    receivers=['The Receiver <you@example.com>']
)

You can define the body of your email using the text parameter for plain text, the html parameter for HTML content, or both to provide a multi-part message.

# Plain text
email.send(
    subject='email subject',
    sender="me@example.com",
    receivers=['you@example.com'],
    text="Hi, this is an email."
)

# HTML body
email.send(
    subject='email subject',
    sender="me@example.com",
    receivers=['you@example.com'],
    html="""
        <h1 style='color: red;'>Hi,</h1>
        <p>this is an email.</p>
    """
)

# Both text and HTML
email.send(
    subject='email subject',
    sender="me@example.com",
    receivers=['you@example.com'],
    text="Hi, this is an email.",
    html="""
        <h1>Hi,</h1>
        <p>this is an email.</p>
    """
)

You can tell Red Mail where your HTML and text templates are located by using set_template_paths(). Red Mail will then automatically create the necessary Jinja environments for you. You can also specify custom paths for rendering embedded tables using html_table and text_table.

from redmail import EmailSender

email = EmailSender(host="localhost", port=0)

# Set standard template paths
email.set_template_paths(
    html="path/html/templates",
    text="path/text/templates",
)

# Optionally set custom paths for embedded tables
email.set_template_paths(
    html_table="path/html/tables",
    text_table="path/text/tables",
)

You can set default values for attributes like subject, receivers, sender, etc., directly on the EmailSender instance. These defaults will be used by .send() if the specific attribute is not provided in the method call.

email = EmailSender(host='localhost', port=0)
email.subject = "email subject"
email.receivers = ["you@example.com"]

# This uses the default subject and receiver set above
email.send(
    sender="me@example.com",
    subject="important email"
)