# Email (Incoming - IMAP)

The Zuar Runner IMAP Job allows you access attachments present in *UNREAD* email
messages in an email server via the IMAP protocol and download those
attachments to Zuar Runner's file system. Once downloaded to Zuar Runner, the files can
then be used as input by subsequent jobs
([CSV](../csv), [Excel](../excel),
[JSON](../json), etc.) to create database tables. 

The IMAP job supports three different IMAP authentication methods: basic,
Gmail OAuth2, and Microsoft 365 OAuth 2.  The steps necessary to authenticate
differ based on the method; all three are described on this page.

While authentication related fields in the wizard differ based on the
authentication method, some wizard fields are common to all methods.  Those
common fields are described in the :ref:`common_configuration` section
of this page.

## Prerequisites

Before you can create an IMAP job, it may be necessary for you to configure
your IMAP account to allow Zuar Runner to access your mail and attachments.

IMAP providers that no longer allow the use of Basic Auth usually support
OAuth2 for authentication, as it is more secure than Basic Auth.  Zuar Runner
supports the use of OAuth2 to access email via IMAP for Gmail and
Microsoft 365.  Although OAuth2 is a standard, each IMAP provider implements
it differently and, thus, instructions differ based on provider.

### Prerequisites - Basic Authentication - Standard IMAP

If you use an IMAP provider that allows access to your mail via a
username/password login (also called "Basic Auth"), you can use the IMAP
wizard immediately to create your IMAP job (i.e., there are no
prerequisites). If this describes your situation,
you can proceed directly to the next section: :ref:`basic_create_job`.

### Prerequisites - Gmail

If you are using a Gmail account, you must, in your Google Cloud Platform
account, create a project, enable the IMAP API, and configure OAuth consent.
This page contains detailed instructions on performing these tasks:
[Gmail - Setup Account](gmail-setup-account).

### Prerequisites - Microsoft 365

If you are using a Microsoft 365 account, you must, in Azure Active Directory,
register an application, create credentials, enable the IMAP API, and grant
permissions to the app. This page contains detailed instructions on performing
these tasks: [Microsoft 365 - Setup Account](m365-setup-account)

## Create an IMAP Job

With the prerequisites out of the way, you are now able to run the IMAP wizard
and create an IMAP job.  Follow the steps in one of the following sections.

.. _basic_create_job:

### Create Job - Basic Authentication - Standard IMAP

If you are using basic authentication, all you'll need are the username,
password, and IMAP server name.  Follow the instructions here:
[Basic Authentication - Create Job](basic-create-job).

### Create Job - Gmail

If you are using Gmail, you'll need the credentials you created earlier, the
project id, and email address.  The wizard will automatically connect to
Google to authenticate your account using OAuth2.  Follow the instructions
here: [Gmail - Create Job](gmail-create-job)

### Create Job - Microsoft 365

If you are using Microsoft 365, you'll need the tenant id, client id, and
client secret that you created earlier.  The wizard will automatically connect
to Microsoft and perform the OAuth device code challenges to gain authenticate
with your account.  Follow the instructions here:
[Microsoft 365 - Create Job](m365-create-job)

.. _common_configuration:

## Common Configuration Options

The following wizard fields are common to all authentication methods.

`IMAP SERVER URI`

The hostname of the IMAP server to use.

- Basic Authentication - Standard IMAP: use the server's hostname
- Gmail: use `imap.gmail.com`
- Outlook: use `outlook.office365.com`

`PROVIDED CREDENTIAL NAME`

If you are providing credentials, the credentials will be saved using this name.

`USER EMAIL`

The email address from which attachments will be obtained.

`MAIL LABEL`

- This is the folder location of the emails.
- This is case insensitive.
- Removing this key/value pair or using `inbox` means you are looking at files in the inbox.
- In order to look at lower level folders use quotes and forward slashes to
  separate the nested folders. For example: `Inbox/csv`

  .. NOTE:: 

   Gmail's inbox structure uses "Labels" that may behave differently than m365 as they are more like filters and not necessarily folder/directories. It is recommended that a Label be created with rules to filter only the target emails once received. Specify the Label in the `MAIL LABEL` input of the job configuration.

`FORMAT OF AN OUTPUT FILE NAME`

- This is how Zuar Runner will name the output file in the file manager.
- `{safe_root}` represents the original file name.
- `{ext}` represents the original file extension.
- You can alter the file name by adding text (Example
  `activity_visits_{safe_root}.{ext}`) and/or datetime attributes (Example
  `{safe_root}_{year}{month:02d}{day:02d}.{ext}`).
- Leave the file names unchanged by removing this key/value pair or using
  `{safe_root}.{ext}`

## Example Job Config
```json
    {
        "credentials": "Credential Name",
        "filename_format": "{safe_root}.{ext}",
        "label": "path/to/folder",
        "server": "outlook.office365.com"
    }
```

..
   This is a comment.  The following toctree is used to inhibit
   warnings about the following files not being included in a toctree

.. toctree::
   :hidden:

   basic-create-job
   gmail-create-job
   gmail-setup-account
   m365-create-job
   m365-setup-account