References

Sender

class redmail.EmailSender(host, port, username=None, password=None, cls_smtp=<class 'smtplib.SMTP'>, use_starttls=True, domain=None, **kwargs)

Red Mail Email Sender

Parameters

• host (str) – SMTP host address.

• port (int) – Port to the SMTP server.

• username (str, optional) – User name to authenticate on the server.

• password (str, optional) – User password to authenticate on the server.

• cls_smtp (smtplib.SMTP) – SMTP class to use for connection. See options from Python smtplib docs.

• use_starttls (bool) – Whether to use STARTTLS when connecting to the SMTP server.

• user_name (str, optional) – Deprecated alias for username. Please use username instead.

• domain (str, optional) – Portion of the generated IDs after “@” which strengthens the uniqueness of the generated IDs. Used in the Message-ID header and in the Content-IDs of the embedded imaged in the HTML body. Usually not needed to be set. Defaults to the fully qualified domain name.

• **kwargs (dict) – Additional keyword arguments are passed to initiation in cls_smtp. These are stored as attribute kws_smtp

sender

Address for sending emails if it is not specified in the send method.

Type

str

receivers

Addresses to send emails if not specified in the send method.

Type

list of str

cc

Carbon copies of emails if not specified in the send method.

Type

list of str

bcc

Blind carbon copies of emails if not specified in the send method.

Type

list of str

subject

Subject of emails if not specified in the send method.

Type

str

text

Text body of emails if not specified in the send method.

Type

str

html

HTML body of emails if not specified in the send method.

Type

str

text_template

Name of the template to use as the text body of emails if not specified in the send method.

Type

str

html_template

Name of the template to use as the HTML body of emails if not specified in the send method.

Type

str

use_jinja

Use Jinja to render text/HTML. If Jinja is disabled, images cannot be embedded to HTML, templates have no effect and body_params are not used. Defaults True

Type

bool

templates_html

Jinja environment used for loading HTML templates if html_template is specified in send.

Type

jinja2.Environment

templates_text

Jinja environment used for loading text templates if text_template is specified in send.

Type

jinja2.Environment

default_html_theme

Jinja template from templates_html_table used for styling tables for HTML body.

Type

str

default_text_theme

Jinja template from templates_text_table used for styling tables for text body.

Type

str

templates_html_table

Jinja environment used for loading templates for table styling for HTML bodies.

Type

jinja2.Environment

templates_text_table

Jinja environment used for loading templates for table styling for text bodies.

Type

jinja2.Environment

headers

Additional email headers. Will also override the other generated email headers such as From:, To and Date:.

Type

dict

kws_smtp

Keyword arguments passed to cls_smtp when connecting to the SMTP server.

Type

dict

connection

Connection to the SMTP server. Created and closed before and after sending each email unless there is an existing connection.

Type

smtplib.SMTP, None

Examples

email = EmailSender(server="smtp.mymail.com", port=123)
email.send(
    subject="Example Email",
    sender="me@example.com",
    receivers=["you@example.com"],
)

send(subject=None, sender=None, receivers=None, cc=None, bcc=None, headers=None, html=None, text=None, html_template=None, text_template=None, body_images=None, body_tables=None, body_params=None, attachments=None)

Send an email.

Parameters

• subject (str) – Subject of the email.

• sender (str, optional) – Email address the email is sent from. Note that some email services might not respect changing sender address (for example Gmail).

• receivers (list, optional) – Receivers of the email.

• cc (list, optional) – Cc or Carbon Copy of the email. Additional recipients of the email.

• bcc (list, optional) – Blind Carbon Copy of the email. Additional recipients of the email that don’t see who else got the email.

• headers (dict, optional) – Additional email headers. Will also override the other generated email headers such as From:, To and Date:.

• html (str, optional) – HTML body of the email. This is processed by Jinja and may contain loops, parametrization etc. See Jinja documentation.

• text (str, optional) –

  Text body of the email. This is processed by Jinja and may contain loops, parametrization etc. See Jinja documentation.

• html_template (str, optional) – Name of the HTML template loaded using Jinja environment specified in templates_html attribute. Specify either html or html_template.

• text_template (str, optional) – Name of the text template loaded using Jinja environment specified in templates_text attribute. Specify either text or text_template.

• body_images (dict of bytes, dict of path-like, dict of plt Figure, dict of PIL Image, optional) – HTML images to embed with the html. The key should be as Jinja variables in the html and the values represent images (path to an image, bytes of an image or image object).

• body_tables (dict of Pandas dataframes, optional) – HTML tables to embed with the html. The key should be as Jinja variables in the html and the values are Pandas DataFrames.

• body_params (dict, optional) – Extra Jinja parameters passed to the HTML and text bodies.

• use_jinja (bool) – Use Jinja to render text/HTML. If Jinja is disabled, body content cannot be embedded, templates have no effect and body parameters do nothing.

• attachments (dict, optional) – Attachments of the email. If dict value is string, the attachment content is the string itself. If path, the attachment is the content of the path’s file. If dataframe, the dataframe is turned to bytes or text according to the file extension in dict key.

Examples

Simple example:

from redmail import EmailSender

email = EmailSender(
    host='localhost',
    port=0,
    username='me@example.com',
    password='<PASSWORD>'
)
email.send(
    subject="An email",
    sender="me@example.com",
    receivers=['you@example.com'],
    text="Hi, this is an email.",
    html="<h1>Hi, </h1><p>this is an email.</p>"
)

See more examples from docs

Returns

Email message.

Return type

EmailMessage

Notes

See also Jinja documentation for utilizing Jinja in html and text arguments or for using Jinja templates with html_template and text_template arguments.

get_message(subject=None, sender=None, receivers=None, cc=None, bcc=None, html=None, text=None, html_template=None, text_template=None, body_images=None, body_tables=None, body_params=None, attachments=None, headers=None, use_jinja=None)

Get the email message

get_receivers(receivers)

Get receivers of the email

get_cc(cc)

Get carbon copy (cc) of the email

get_bcc(bcc)

Get blind carbon copy (bcc) of the email

get_headers(headers)

Get additional headers

get_sender(sender)

Get sender of the email

send_message(msg)

Send the created message

connect()

Connect to the SMTP Server

close()

Close (quit) the connection

get_server()

Connect and get the SMTP Server

property is_alive

Check if there is a connection to the SMTP server

Type

bool

get_params(sender)

Get Jinja parametes passed to both text and html bodies

get_html_params(extra=None, **kwargs)

Get Jinja parameters passed to HTML body

get_text_params(extra=None, **kwargs)

Get Jinja parameters passed to text body

get_html_table_template(layout=None)

Get Jinja template for tables in HTML body

get_html_template(layout=None)

Get pre-made Jinja template for HTML body

get_text_table_template(layout=None)

Get Jinja template for tables in text body

get_text_template(layout=None)

Get pre-made Jinja template for text body

set_template_paths(html=None, text=None, html_table=None, text_table=None)

Create Jinja envs for body templates using given paths

This is a shortcut for manually setting them:

sender.templates_html = jinja2.Environment(loader=jinja2.FileSystemLoader(...))
sender.templates_text = jinja2.Environment(loader=jinja2.FileSystemLoader(...))
sender.templates_html_table = jinja2.Environment(loader=jinja2.FileSystemLoader(...))
sender.templates_text_table = jinja2.Environment(loader=jinja2.FileSystemLoader(...))

copy()

Shallow copy EmailSender

Format Classes

class redmail.models.EmailAddress(address)

Format class for email addresses.

This class is useful manipulate the addresses in templates with minimal effort. More about email addresses from Wikipedia.

Parameters

address (str) – Email address as string.

class redmail.models.Error(content_type='text', exception=None)

Format class for errors including the exception and traceback.

Parameters

• contet_type (str) – Content type for which the error is meant to be rendered on.

• exception (Exception) – Exception object. If not passed, current stack trace is used.

Logging Classes

class redmail.EmailHandler(level=0, email=None, **kwargs)

Logging handler for sending a log record as an email

Parameters

• level (int) – Log level of the handler

• email (EmailSender) – Sender instance to be used for sending the log records.

• kwargs (dict) – Keyword arguments for creating the sender if email was not passed.

Examples

Minimal example:

handler = EmailHandler(
    host="smtp.myhost.com", port=0,
    sender="no-reply@example.com",
    receivers=["me@example.com"],
)

Customized example:

from redmail import EmailSender
email = EmailSender(
    host="smtp.myhost.com",
    port=0
)
email.email = "no-reply@example.com"
email.receivers = ["me@example.com"]
email.html = '''
    <h1>Record: {{ record.levelname }}</h1>
    <pre>{{ record.msg }}</pre>
    <h2>Info</h2>
    <ul>
        <li>Path: {{ record.pathname }}</li>
        <li>Function: {{ record.funcName }}</li>
        <li>Line number: {{ record.lineno }}</li>
    </ul>
'''
handler = EmailHandler(email=email)

import logging
logger = logging.getLogger()
logger.addHandler(handler)

class redmail.MultiEmailHandler(capacity=None, email=None, **kwargs)

Logging handler for sending multiple log records as an email

Parameters

• capacity (int) – Number of

• email (EmailSender) – Sender instance to be used for sending the log records.

• kwargs (dict) – Keyword arguments for creating the sender if email was not passed.

Examples

Minimal example:

handler = MultiEmailHandler(
    host="smtp.myhost.com", port=0,
    sender="no-reply@example.com",
    receivers=["me@example.com"],
)

Customized example:

from redmail import EmailSender
email = EmailSender(
    host="smtp.myhost.com",
    port=0
)
email.sender = "no-reply@example.com"
email.receivers = ["me@example.com"]
email.html = '''
    <h1>Record: {{ record.levelname }}</h1>
    <pre>{{ record.msg }}</pre>
    <h2>Info</h2>
    <ul>
        <li>Path: {{ record.pathname }}</li>
        <li>Function: {{ record.funcName }}</li>
        <li>Line number: {{ record.lineno }}</li>
    </ul>
'''
handler = EmailHandler(sender=email)

import logging
logger = logging.getLogger()
logger.addHandler(handler)

Email Strucure (MIME)

This section covers how Red Mail structures emails with MIME parts. You may need this information if you are creating unit tests or if you face problems with rendering your emails by your email provider.

Empty Email

Empty email has no MIME parts attached. It only has the headers.

Email with a text body

• text/plain

Email with an HTML body

• multipart/mixed

  • multipart/alternative

    • text/html

Email with an HTML body and inline JPG image

• multipart/mixed

  • multipart/alternative

    • multipart/related

      • text/html

      • image/jpg

Email with an attachment

• multipart/mixed

  • application/octet-stream

Email with all elements

• multipart/mixed

  • multipart/alternative

    • text/plain

    • multipart/related

      • text/html

      • image/jpg

  • application/octet-stream