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.

Module Contents

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.

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

Bases: airflow.hooks.base.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]
__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, 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.

  • 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, 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.

  • 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, 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.

  • 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.

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.

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

Was this entry helpful?