mailsuite

A Python package to simplify receiving, parsing, and sending email

Features

  • Receive emails via IMAP

    • Retrieve email from any folder

    • Create new folders

    • Move messages to other folders

    • Delete messages

    • Monitor folders for new messages using the IMAP IDLE command

    • Always use / as the folder hierarchy separator, and convert to the server’s hierarchy separator in the background

    • Always remove folder name characters that conflict with the server’s hierarchy separators

    • Prepend the namespace to the folder path when required

    • Automatically reconnect when needed

    • Work around quirks in Gmail/G-suite, Office 365, Exchange, Dovcot, and DavMail

  • Consistent email parsing

    • SHA256 hashes of attachments

  • Simplified email sending via SMTP

    • Uses opportunistic encryption (STARTTLS) by default

    • Easily add attachments, plain text, and HTML

API

mailsuite.imap

class mailsuite.imap.IMAPClient(host, username, password, port=None, ssl=True, verify=True, timeout=30, max_retries=4, initial_folder='INBOX', idle_callback=None, idle_timeout=30)[source]

A simplified IMAP client

create_folder(folder_path, _attempt=1)[source]

Creates an IMAP folder at the given path

Parameters
  • folder_path (str) – The path of the folder to create

  • _attempt (int) – The attempt number

delete_messages(msg_uids, silent=True, _attempt=1)[source]

Deletes the given messages by Message UIDs

Parameters
  • msg_uids (list) – A list of UIDs of messages to delete

  • silent (bool) – Do it silently

  • _attempt (int) – The attempt number

fetch_message(msg_uid, parse=False, _attempt=1)[source]

Fetch a message by UID, and optionally parse it

Parameters
  • msg_uid (int) – The message UID

  • parse (bool) – Return parsed results from mailparser

  • _attempt (int) – The attempt number

Returns

The raw mail message, including headers dict: A parsed email message

Return type

str

move_messages(msg_uids, folder_path, _attempt=1)[source]

Move the emails with the given UIDs to the given folder

Parameters
  • msg_uids – A UID or list of UIDs of messages to move

  • folder_path (str) – The path of the destination folder

  • _attempt (int) – The attempt number

reset_connection()[source]

Resets the connection to the IMAP server

exception mailsuite.imap.MaxRetriesExceeded[source]

Raised when the maximum number of retries in exceeded

mailsuite.smtp

exception mailsuite.smtp.SMTPError[source]

Raised when a SMTP error occurs

mailsuite.smtp.send_email(host, message_from, message_to=None, message_cc=None, message_bcc=None, port=0, require_encryption=False, verify=True, username=None, password=None, envelope_from=None, subject=None, message_headers=None, attachments=None, plain_message=None, html_message=None)[source]

ESend an email using a SMTP relay

Parameters
  • host (str) – Mail server hostname or IP address

  • message_from (str) – The value of the message from header

  • message_to (list) – A list of addresses to send mail to

  • message_cc (list) – A List of addresses to Carbon Copy (CC)

  • (list (message_bcc) – A list of addresses to Blind Carbon Copy (BCC)

  • port (int) – Port to use

  • require_encryption (bool) – Require a SSL/TLS connection from the start

  • verify (bool) – Verify the SSL/TLS certificate

  • username (str) – An optional username

  • password (str) – An optional password

  • envelope_from (str) – Overrides the SMTP envelope “mail from” header

  • subject (str) – The message subject

  • message_headers (dict) – Custom message headers

  • attachments (list) – A list of tuples, containing filenames as bytes

  • plain_message (str) – The plain text message body

  • html_message (str) – The HTML message body

mailsuite.utils

exception mailsuite.utils.EmailParserError[source]

Raised when an error parsing the email occurs

mailsuite.utils.convert_outlook_msg(msg_bytes)[source]

Uses the msgconvert Perl utility to convert an Outlook MS file to standard RFC 822 format

Parameters

msg_bytes (bytes) – the content of the .msg file

Returns

A RFC 822 string

mailsuite.utils.create_email(message_from, message_to=None, message_cc=None, subject=None, message_headers=None, attachments=None, plain_message=None, html_message=None)[source]

Creates an RFC 822 email message and returns it as a string

Parameters
  • message_from (str) – The value of the message from header

  • message_to (list) – A list of addresses to send mail to

  • message_cc (list) – A List of addresses to Carbon Copy (CC)

  • subject (str) – The message subject

  • message_headers (dict) – Custom message headers

  • attachments (list) – A list of tuples, containing filenames as bytes

  • plain_message (str) – The plain text message body

  • html_message (str) – The HTML message body

Returns

A RFC 822 email message

Return type

str

mailsuite.utils.decode_base64(data)[source]

Decodes a base64 string, with padding being optional

Parameters

data – A base64 encoded string

Returns

The decoded bytes

Return type

bytes

mailsuite.utils.get_filename_safe_string(string, max_length=146)[source]

Converts a string to a string that is safe for a filename :param string: A string to make safe for a filename :type string: str :param max_length: Truncate strings longer than this length :type max_length: int

Warning

Windows has a 260 character length limit on file paths

Returns

A string safe for a filename

Return type

str

mailsuite.utils.get_reverse_dns(ip_address, cache=None, nameservers=None, timeout=2.0)[source]

Resolves an IP address to a hostname using a reverse DNS query

Parameters
  • ip_address (str) – The IP address to resolve

  • cache (ExpiringDict) – Cache storage

  • nameservers (list) – A list of one or more nameservers to use

  • public DNS resolvers by default) ((Cloudflare's) –

  • timeout (float) – Sets the DNS query timeout in seconds

Returns

The reverse DNS hostname (if any)

Return type

str

mailsuite.utils.is_outlook_msg(content)[source]

Checks if the given content is a Outlook msg OLE file

Parameters

content – Content to check

Returns

A flag the indicates if a file is a Outlook MSG file

Return type

bool

mailsuite.utils.parse_email(data, strip_attachment_payloads=False)[source]

A simplified email parser

Parameters
  • data – The RFC 822 message string, or MSG binary

  • strip_attachment_payloads (bool) – Remove attachment payloads

Returns (dict): Parsed email data

mailsuite.utils.query_dns(domain, record_type, cache=None, nameservers=None, timeout=2.0)[source]

Queries DNS

Parameters
  • domain (str) – The domain or subdomain to query about

  • record_type (str) – The record type to query for

  • cache (ExpiringDict) – Cache storage

  • nameservers (list) – A list of one or more nameservers to use

  • public DNS resolvers by default) ((Cloudflare's) –

  • timeout (float) – Sets the DNS timeout in seconds

Returns

A list of answers

Return type

list

Indices and tables