airflow.providers.imap.hooks.imap¶

This module provides everything to search mail for a specific attachment and download it.

It uses the imaplib library that is already integrated in python 3.

Classes¶

`ImapHook`	This hook connects to a mail server by using the imap protocol.
`Mail`	This class simplifies working with mails returned by the imaplib client.
`MailPart`	This class is a wrapper for a Mail object's part and gives it more features.

Module Contents¶

class airflow.providers.imap.hooks.imap.ImapHook(imap_conn_id=default_conn_name)[source]¶

Bases: airflow.providers.common.compat.sdk.BaseHook

This hook connects to a mail server by using the imap protocol.

Note

Please call this Hook as context manager via with to automatically open and close the connection to the mail server.

Parameters:: imap_conn_id (str) – The imap connection id that contains the information used to authenticate the client.

conn_name_attr = 'imap_conn_id'[source]¶

default_conn_name = 'imap_default'[source]¶

conn_type = 'imap'[source]¶

hook_name = 'IMAP'[source]¶

imap_conn_id = 'imap_default'[source]¶

mail_client: imaplib.IMAP4_SSL | imaplib.IMAP4 | None = None[source]¶

__enter__()[source]¶

__exit__(exc_type, exc_val, exc_tb)[source]¶

get_conn()[source]¶

Login to the mail server.

Note

Please call this Hook as context manager via with to automatically open and close the connection to the mail server.

Returns:: an authorized ImapHook object.
Return type:: ImapHook

has_mail_attachment(name, *, check_regex=False, max_mails=None, mail_folder='INBOX', mail_filter='All')[source]¶

Check the mail folder for mails containing attachments with the given name.

Parameters:

name (str) – The name of the attachment that will be searched for.
check_regex (bool) – Checks the name for a regular expression.
max_mails (int | None) – Maximum number of latest emails to process. Must be a positive integer, or None when unlimited. Defaults to None.
mail_folder (str) – The mail folder where to look at.
mail_filter (str) – If set other than ‘All’ only specific mails will be checked. See imaplib.IMAP4.search() for details.

Returns:

True if there is an attachment with the given name and False if not.

Return type:

bool

retrieve_mail_attachments(name, *, check_regex=False, latest_only=False, max_mails=None, mail_folder='INBOX', mail_filter='All', not_found_mode='raise')[source]¶

Retrieve mail’s attachments in the mail folder by its name.

Parameters:

name (str) – The name of the attachment that will be downloaded.
check_regex (bool) – Checks the name for a regular expression.
latest_only (bool) – If set to True it will only retrieve the first matched attachment.
max_mails (int | None) – Maximum number of latest emails to process. Must be a positive integer, or None when unlimited. Defaults to None.
mail_folder (str) – The mail folder where to look at.
mail_filter (str) – If set other than ‘All’ only specific mails will be checked. See imaplib.IMAP4.search() for details.
not_found_mode (str) – Specify what should happen if no attachment has been found. Supported values are ‘raise’, ‘warn’ and ‘ignore’. If it is set to ‘raise’ it will raise an exception, if set to ‘warn’ it will only print a warning and if set to ‘ignore’ it won’t notify you at all.

Returns:

a list of tuple each containing the attachment filename and its payload.

Return type:

list[tuple]

download_mail_attachments(name, local_output_directory, *, check_regex=False, latest_only=False, max_mails=None, mail_folder='INBOX', mail_filter='All', not_found_mode='raise')[source]¶

Download mail’s attachments in the mail folder by its name to the local directory.

Parameters:

name (str) – The name of the attachment that will be downloaded.
local_output_directory (str) – The output directory on the local machine where the files will be downloaded to.
check_regex (bool) – Checks the name for a regular expression.
latest_only (bool) – If set to True it will only download the first matched attachment.
max_mails (int | None) – Maximum number of latest emails to process. Must be a positive integer, or None when unlimited. Defaults to None.
mail_folder (str) – The mail folder where to look at.
mail_filter (str) – If set other than ‘All’ only specific mails will be checked. See imaplib.IMAP4.search() for details.
not_found_mode (str) – Specify what should happen if no attachment has been found. Supported values are ‘raise’, ‘warn’ and ‘ignore’. If it is set to ‘raise’ it will raise an exception, if set to ‘warn’ it will only print a warning and if set to ‘ignore’ it won’t notify you at all.

class airflow.providers.imap.hooks.imap.Mail(mail_body)[source]¶

Bases: airflow.utils.log.logging_mixin.LoggingMixin

This class simplifies working with mails returned by the imaplib client.

Parameters:: mail_body (str) – The mail body of a mail received from imaplib client.

mail[source]¶

has_attachments()[source]¶

Check the mail for a attachments.

Returns:: True if it has attachments and False if not.
Return type:: bool

get_attachments_by_name(name, check_regex, find_first=False)[source]¶

Get all attachments by name for the mail.

Parameters:

name (str) – The name of the attachment to look for.
check_regex (bool) – Checks the name for a regular expression.
find_first (bool) – If set to True it will only find the first match and then quit.

Returns:

a list of tuples each containing name and payload where the attachments name matches the given name.

Return type:

list[tuple[Any, Any]]

class airflow.providers.imap.hooks.imap.MailPart(part)[source]¶

This class is a wrapper for a Mail object’s part and gives it more features.

Parameters:: part (Any) – The mail part in a Mail object.

part[source]¶

is_attachment()[source]¶

Check if the part is a valid mail attachment.

Returns:: True if it is an attachment and False if not.
Return type:: bool

has_matching_name(name)[source]¶

Check if the given name matches the part’s name.

Parameters:: name (str) – The name to look for.
Returns:: True if it matches the name (including regular expression).
Return type:: tuple[Any, Any] | None

has_equal_name(name)[source]¶

Check if the given name is equal to the part’s name.

Parameters:: name (str) – The name to look for.
Returns:: True if it is equal to the given name.
Return type:: bool

get_file()[source]¶

Get the file including name and payload.

Returns:: the part’s name and payload.
Return type:: tuple