API

mailsuite.imap

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

A simplified IMAP client

create_folder(folder_path: str, _attempt: int = 1)[source]

Creates an IMAP folder at the given path

Parameters:

  • folder_path – The path of the folder to create

  • _attempt – The attempt number

delete_messages(msg_uids: List[int] | List[str] | str | int, silent: bool = True, _attempt: int = 1)[source]

Deletes the given messages by Message UIDs

Parameters:

  • msg_uids – A list of UIDs of messages to delete

  • silent – Do it silently

  • _attempt – The attempt number

fetch_message(msg_uid: int, parse: bool = False, _attempt: int = 1) → str | Dict[source]

Fetch a message by UID, and optionally parse it

Parameters:

  • msg_uid – The message UID

  • parse – Return parsed results from mailparser

  • _attempt – The attempt number

Returns:

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

Return type:

str

move_messages(msg_uids: int | List[int], folder_path: str, _attempt: int = 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 – The path of the destination folder

  • _attempt – 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: str, message_from: str, message_to: List[str] = None, message_cc: List = None, message_bcc: List = None, port: int = 0, require_encryption: bool = False, verify: bool = True, username: str = None, password: str = None, envelope_from: str = None, subject: str = None, message_headers: Dict = None, attachments: Tuple[str, bytes] = None, plain_message: str = None, html_message: str = None)[source]

Send an email using a SMTP relay

Parameters:

  • host – Mail server hostname or IP address

  • message_from – The value of the message from header

  • message_to – A list of addresses to send mail to

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

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

  • port – Port to use

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

  • verify – Verify the SSL/TLS certificate

  • username – An optional username

  • password – An optional password

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

  • subject – The message subject

  • message_headers – Custom message headers

  • attachments – A list of tuples, containing filenames and bytes

  • plain_message – The plain text message body

  • html_message – The HTML message body

mailsuite.utils

exception mailsuite.utils.EmailParserError[source]

Raised when an email parsing error occurs

mailsuite.utils.convert_outlook_msg(msg_bytes: bytes) → str[source]

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

Warning

Anomalies are introduced during conversion that make the results unsuitable for forensic analysis.

Parameters:

msg_bytes – the content of the .msg file

Returns: A RFC 822 string

mailsuite.utils.create_email(message_from: str, message_to: List[str] = None, message_cc: List[str] = None, subject: str = None, message_headers: dict = None, attachments: List[Tuple[str, bytes]] = None, plain_message: str = None, html_message: str = None) → str[source]

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

Parameters:

  • message_from – The value of the message from header

  • message_to – A list of addresses to send mail to

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

  • subject – The message subject

  • message_headers – Custom message headers

  • attachments – A list of tuples, containing a filename and bytes

  • plain_message – The plain text message body

  • html_message – The HTML message body

Returns: A RFC 822 email message

mailsuite.utils.decode_base64(data: str) → bytes[source]

Decodes a base64 string, with padding being optional

Parameters:

data – A base64 encoded string

Returns: The decoded bytes

mailsuite.utils.from_trusted_domain(message: str | IOBase | Dict, trusted_domains: List[str] | str, include_sld: bool = True, allow_multiple_authentication_results: bool = False, use_authentication_results_original: bool = False) → bool[source]

Checks if an email is from a trusted domain based on the contents of the Authentication-Results header

Warning

Authentication results are not verified by this function, so only use it on emails that have been received by trusted mail servers, and not on third-party emails.

Warning

Set allow_multiple_authentication_results to True if and only if the receiving mail service splits the results of each authentication method in separate Authentication-Results headers and always includes DMARC results.

Warning

Set use_authentication_results_original to True if and only if you use an email security gateway that adds an Authentication-Results-Original header, such as Proofpoint or Cisco IronPort. This does not include API-based email security solutions, such as Abnormal Security.

Parameters:

  • message – An email

  • trusted_domains – A list of trusted domains

  • include_sld – Also return True if the Second-Level Domain (SLD) of an authenticated domain is in trusted_domains

  • allow_multiple_authentication_results – Allow multiple Authentication-Results-Original headers

  • use_authentication_results_original – Use the Authentication-Results-Original header instead of the Authentication-Results header

Returns:

Results of the check

mailsuite.utils.get_filename_safe_string(string: str, max_length: int = 146) → str[source]

Converts a string to a string that is safe for a filename

Parameters:

  • string – A string to make safe for a filename

  • max_length – Truncate strings longer than this length

Warning

Windows has a 260 character length limit on file paths

Returns: A string safe for a filename

mailsuite.utils.get_reverse_dns(ip_address: str, cache: ExpiringDict = None, nameservers: List[str] = None, timeout: float | int = 2.0) → str | None[source]

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

Parameters:

  • ip_address – The IP address to resolve

  • cache – Cache storage

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

  • timeout – Sets the DNS query timeout in seconds

Returns: The reverse DNS hostname (if any)

mailsuite.utils.is_outlook_msg(content: bytes) → bool[source]

Checks if the given content is an Outlook msg OLE file

Parameters:

content – Content to check

Returns: A flag the indicates if a file is an Outlook MSG file

mailsuite.utils.parse_authentication_results(authentication_results: str | List, from_domain: str = None) → Dict | List[Dict][source]

Parses and normalizes an Authentication-Results header value or list of values

Parameters:

  • authentication_results – The value of the header or list of values

  • from_domain – The message From domain

Returns: A parsed header value or list of parsed values

mailsuite.utils.parse_dkim_signature(dkim_signature: str | List) → Dict | List[source]

Parses a DKIM-Signature header value or list of values

Parameters:

dkim_signature – A DKIM-Signature header value or list of values

Returns: A parsed DKIM-Signature header value or parsed values

mailsuite.utils.parse_email(data: str | bytes, strip_attachment_payloads: bool = False) → Dict[source]

A simplified email parser

Parameters:

  • data – A file path, RFC 822 message string, or Microsoft .msg bytes

  • strip_attachment_payloads – Remove attachment payloads

Returns: Parsed email data

Note

Attachment dictionaries with binary payloads contain the value binary: True use mailsuite.utils.decode_base64 to convert the payload to bytes.

mailsuite.utils.query_dns(domain: str, record_type: str, cache: ExpiringDict = None, nameservers: List[str] = None, timeout: float | int = 2.0)[source]

Queries DNS

Parameters:

  • domain – The domain or subdomain to query about

  • record_type – The record type to query for

  • cache – Cache storage

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

  • timeout – DNS timeout in seconds

Returns:

A list of answers