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 attributekws_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
andDate:
.- 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
andDate:
.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 eitherhtml
orhtml_template
.text_template (str, optional) – Name of the text template loaded using Jinja environment specified in
templates_text
attribute. Specify eithertext
ortext_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
andtext
arguments or for using Jinja templates withhtml_template
andtext_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