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, Excel, 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 Common Configuration Options 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: Create Job - Basic Authentication - Standard IMAP.

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.

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

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.

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.

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

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

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

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¶

{
    "credentials": "Credential Name",
    "filename_format": "{safe_root}.{ext}",
    "label": "path/to/folder",
    "server": "outlook.office365.com"
}