Mailbox IMAP OAuth
The Qlik Mailbox IMAP connector lets you fetch emails and email content, such as information about attachments, from any mailbox that uses the IMAP email protocol.
Creating an OAuth application on your provider
To use this connector, you need to create an OAuth application on your chosen third-party provider (for example, Gmail, Outlook, etc). Qlik does not provide OAuth applications for these services.
The creation requirement and restrictions (such as account type) are determined by each provider. Your provider controls token expiration and refresh policies.
Refer to your provider’s documentation for instructions on creating OAuth applications.
Authentication
To access your IMAP server, you need to authenticate the connector with your IMAP server details. After you create a new connection and select IMAP as your connector, you need to enter the server address along with your username and password. You also need to choose an appropriate port and an SSL mode for the connection to the server.
OAuth
| Authentication field | Description | Required |
|---|---|---|
| OAuth Endpoint | Enter the OAuth URL for authorization calls | Yes |
| OAuth Token Endpoint | Enter the OAuth URL to obtain the token from the server | Yes |
| OAuth Scopes | Enter the scope URI |
Yes |
| OAuth Client ID | Client ID for IMAP OAuth authentication | Yes |
| OAuth Client Secret | Client secret for IMAP OAuth authentication | Yes |
| Prompt/consent level | This instructs the type of OAuth authentication request. Consent forces to show the authorization consent to the application. select_account forces to show the account selector. The service you use dictates which OAuth request is required. | Yes |
| IMAP Server | Enter the IMAP server address. | Yes |
| Port | Default port is 465 for implicit SSL/TLS. Default port is 587 for explicit SSL (StartTLS). | Yes |
| SSL Mode | Select implicit (SSL/TLS) or explicit (StartTLS). | Yes |
Account properties
Credentials
Credentials are used to prove that a user is allowed to access the data in a connection.
There are two types of credentials that can be used when making a connection in Qlik Sense SaaS. If you leave the User defined credentials check box deselected, then only one set of credentials will be used for the connection. These credentials belong to the connection and will be used by anyone who can access it. For example, if the connection is in a shared space, every user in the space will be able to use these credentials. This one-to-one mapping is the default setting.
If you select User defined credentials, then every user who wants to access this connection will need to input their own credentials before selecting tables or loading data. These credentials belong to a user, not a connection. User defined credentials can be saved and used in multiple connections of the same connector type.
In the Data load editor, you can click the 
underneath the connection to edit your credentials. In spaces or Data manager, you can edit credentials by right-clicking on the connection and selecting Edit Credentials.
See which authentication type applies on each connector's page.
| Account property | Description |
|---|---|
| User defined credentials | Select this check box if you want users that access this connection to have to input their own credentials. Deselect this check box if credentials can be shared with anyone who has access to this connection. |
| New credentials | Drop-down menu item that appears if User defined credentials is selected. |
| Credentials name | Name for the new credential. |
| Existing credentials | Drop-down menu item that appears if User defined credentials is selected. |
| Username | Username for the connection. |
Click the Authenticate button to authenticate the connection.
Supported scopes
IMAP whitelisted scopes
The following scopes are whitelisted for the specific services below. This list is not exhaustive and there could be other supported services
Gmail
For more information, see OAuth 2.0 Mechanism.
-
Gmail requires "https://mail.google.com/" for SMTP.
Microsoft Outlook
For more information, see Authenticate an IMAP, POP or SMTP connection using OAuth.
-
https://outlook.office.com/IMAP.AccessAsUser.All
-
https://outlook.office365.com/.default
Fastmail
For more information, see Fastmail API Documentation.
-
urn:ietf:params:jmap:core
-
urn:ietf:params:jmap:mail
OpenID Connect Standard long term refresh token scope
For more information, see OpenID Connect Core 1.0 incorporating errata set 2.
-
Offline_access
Ways to access your data
To access your IMAP mailbox data, you need to authenticate the connector with your mailbox server details. After you create a new connection and select Mailbox IMAP as your data source, you need to enter the server address for the mailbox you want to connect to, along with your username and password.
Creating a data source connection
Configuring email clients
You need to enable IMAP access for your account, through your mailbox client. The configurations for some of the most common email clients are described below.
Gmail
To download email data from Gmail, you must first ensure that IMAP access is enabled in your Gmail settings.
Do the following:
- Enter imap.gmail.com in the server field.
- Enter your username and password.
Microsoft Exchange
From privately administered Exchange servers
To download data from an exchange server, you must enable IMAP from your exchange server.
Following the Microsoft guidelines for enabling IMAP.
Enable and configure IMAP4 on an Exchange 2016 server
From Office 365 or Microsoft Exchange accounts
To download data from an Office 365 or Exchange account, you must enable IMAP from your exchange account.
POP and IMAP settings for Outlook Office 365 for business
From shared Microsoft Exchange mailboxes
To access shared mailboxes that are not associated with a specific user account, use one of the following formats for your username:
Loading data from tables
After you authenticate the connector with your account credentials, use the tables to fetch your data. The table below outlines some of the use cases for some of the tables that are available.
| Table | Available in | Description |
|---|---|---|
| Folder | Data manager and Data load editor | Use this table to fetch the names and the message count of the folders in your mailbox. |
| MessagesInFolder | Data manager and Data load editor | Use this table to fetch the messages and details from a mailbox folder. The table returns message IDs that are required for other tables. |
| MessageHeaders | Data load editor |
Use this table to fetch the message headers and header values for a message ID. The IMAP message ID is the UID value from the MessagesInFolder table. |
| MessageAttachments | Data load editor |
Use this table to fetch information about message attachments. You need to specify the message ID and the attachment name. The IMAP message ID is the UID value from the MessagesInFolder table. |
To select and load data from a table, enter the required table parameters and click Preview data. Required parameters are marked with an asterisk (*) in the dialog. The table fields are displayed under the Data preview tab. You can select fields individually by selecting the box beside each field name. Select Insert script after you have made your selection.
Troubleshooting
Your Gmail username and password are not accepted when creating a connection
Possible cause
Your Gmail has 2-factor authentication enabled, which is preventing the Mailbox IMAP connector from establishing a connection using your normal credentials. You will see an error message pointing out that your username and password are invalid.
Proposed action
Create an application-specific password, then use this password to configure your Mailbox IMAP connector.
Google blocks sign-in attempt from the Qlik Web Connectors
Possible cause
Google sometimes blocks third-party apps trying to connect to Gmail through IMAP, even on accounts that do not have 2-factor authentication enabled. You may see an error message pointing out that your username and password are invalid, or that you need to log in from a browser.
Proposed action
Allow less secure apps to connect to your Gmail account through IMAP.
Confirm that the sign-in attempt was requested by you, through your Gmail account. It may take some time for the confirmation to take effect.
You cannot connect to the IMAP server
Possible cause
IMAP access is not enabled.
Proposed action
Verify that the email account you want to connect to has IMAP enabled.