Email
=====

.. note::
    It's required to install ``email`` from :ref:`Optional dependencies` section.

Outlook OAuth2
--------------

.. note::
    | In case you'll be using Outlook OAuth2.0 authorization, you need to create & configure new application with the Microsoft identity platform. By the following steps:
    | 1. `Register an application <https://docs.microsoft.com/en-us/azure/active-directory/develop/quickstart-register-app#register-an-application>`_
    | 2. (Optional) In case of using Public(Delegated) Authorization option, you have to enable **Allow public client flows** in **Authentication** section
    | 3. `Add credentials <https://docs.microsoft.com/en-us/azure/active-directory/develop/quickstart-register-app#add-credentials>`_, we currently support only Client's Secret
    | 4. `Add corresponding permissions for Mail <https://docs.microsoft.com/en-us/graph/permissions-reference#mail-permissions>`_, in section **API Permissions**.

    | `Application permissions <https://learn.microsoft.com/en-us/graph/auth-v2-service>`_ - App runs as a background service or daemon without a signed-in user.
    | `Delegated permissions <https://learn.microsoft.com/en-us/graph/auth-v2-user>`_ - App needs to access the API as the signed-in user.

    .. list-table:: Required Permissions based on Authorization option
       :widths: 40 25 35
       :header-rows: 1

       * - Permission
         - Application
         - (Optional) Delegated
       * - ``Mail.ReadWrite``
         - ✅
         - ✅
       * - ``Mail.Send``
         - ✅
         - ✅
       * - ``Mail.ReadWrite.Shared``
         - ❌
         - (for shared mailbox) ✅
       * - ``Mail.Send.Shared``
         - ❌
         - (for shared mailbox) ✅

    .. figure:: ../../images/outlook_permissions.png

        Correct configuration in Azure portal.

    .. warning::
        **Important**, as Application permissions allow a user to access any mailbox, Administrators can configure `application access policy <https://docs.microsoft.com/en-us/graph/auth-limit-mailbox-access>`_ to limit app access to specific mailboxes and not to all the mailboxes in the organization.

        If you need access to a *shared mailbox* (e.g. orders@customer.com), the application access policy needs to be applied to a security-group into which the *shared mailbox* and user belong to.
        More info can be found `here <https://learn.microsoft.com/en-us/exchange/recipients-in-exchange-online/manage-mail-enabled-security-groups>`_.


Client
------

.. automodule:: aiviro.modules.email
    :members: EmailClient, IMAPMessage


Extractor
---------

.. automodule:: aiviro.modules.email.extractor
    :members: EmailExtractor, BaseCallbackStrategy, InvalidEmailNotificationCallback, BaseCondition, OrCondition, HasAttachmentsCondition, FileExtensionCondition, FilenameCondition, ReplaceFilenameCondition, EmailDatetimeCondition, EmailSubjectCondition, NoEmailToExtract