Introduction to Lumiya Mailbox Configuration

First published on: 03/03/2026/4:41 pm

Mailbox whitelisting

When configuring mailboxes, remember that Lumiya must be whitelisted to allow the servers to connect successfully. Below are the details, depending on which server the implementation is being added to. 

Check with your implementation consultant to confirm.

When setting up mailbox information in Lumiya, there are two types:

1. System-generated alerts from Lumiya
2. Documents to receive for processing, e.g., purchase invoices or sales orders

1a. System-generated alerts — Basic SMTP Authentication — Lumiya Configuration

If users want to be notified via email when they have outstanding tasks or approvals, you must configure the system-generated alerts mailbox.

You can do this in Admin > Company Settings

Search for these fields to update:

• Mail host
• Mail password
• Mail port
• Mail username
• Mail from – enter the email address
• Use authentication – Y
• Using SSL – Y

To test if you've successfully created the connection:

• Go to 'Email Message Setup' under the 'Admin' tab
• Select 'Test Email Configuration' at the top right
  • You'll get a pop-up with the current configuration where you can also 'Send a test email'
• Enter your email address and click ‘Send’

You'll receive a test email if you've configured the mailbox correctly.

1b. Modern Authentication – OAuth 2.0 Configuration for SMTP - Client pre-requisites

The following must be done for each client (tenant) that Lumiya needs to send emails through.

An administrator account must create new applications.

Step 1: Register the application

• Login to https://entra.microsoft.com/

• From the menu on the left, pick “Enterprise apps” and then “New application”

• Enter a meaningful name (e.g., Lumiya SMTP)
• Under “Properties”, ensure it is enabled for sign-in and no assignment is required
  • Leaving the visibility to users 'off' ensures it's not used outside the Lumiya process

Step 2: Configure the application

• From the menu on the left, pick “App registrations”
• Find the correct entry
• Click to open it

• Select “Branding & properties”
  • Ensure the “Publisher domain” matches the domain in which the sending account is held
  • If it doesn't match, use the “Update domain” button

• Select “Authentication”, then “Redirect URL configuration
• Then “Add Redirect URI”, followed by “Web” 
• Enter the page in Lumiya where the authorisation process is managed.
  • This is dependent on your Lumiya login, which your implementation consultant will confirm, but will end with /SMTPMicrosoftResponse.aspx
    • e.g., https://app.lumiya.ai/v2/SMTPMicrosoftResponse.aspx

• Select “Authentication” again, then “Settings”
• Ensure “Access tokens” is selected, along with the “single tenant” option

• Select “Certificates & secrets”, then “Client secrets” followed by “New client secret" 
• Enter a description and choose how long it should be valid for
  • NOTE: When this date has been reached, a new secret will need to be created and re-entered into the Lumiya configuration)
• After completing this process, take a record of the “VALUE”, as you will only get to see this once

• Select “API permissions”, then “Add a permission”
• Choose “Microsoft Graph”, followed by “Delegated permissions”
• Find the following from this list to finally add

• Select “Overview” to obtain the “Tenant ID” and the “Client ID”

Step 3: Configure the mailbox

• Login to https://admin.exchange.microsoft.com/
• Select “Recipients > Mailboxes” followed by “Add a shared mailbox”
• Enter the display name and address

• Find the mailbox in the list and click it to get the edit window
• Select “Delegation”
• Under the section “Send as”, click “Edit”

• Click “Add members” to find the admin user(s) you want to use when configuring inside Lumiya
• Create the Authorisation Token via (an admin account at this stage is beneficial)

Step 4: Enable use within Lumiya

IMPORTANT NOTE : It can take up to an hour for the above configurations to be fully applied and propagated throughout Microsoft Office 365, so we recommend performing the next actions the following day.

• A company setting should be enabled for 'Using Office365 SMTP'
• “Can Send Emails” should be “Y” whilst testing

• You can then use the 'Email Message Setup' page to enter these details
  • Tenant ID (obtained in step 2 above)
  • Client ID (obtained in step 2 above)
  • Secret Value (obtained in step 2 above)
  • Email address to send via (configured in step 3 above)

• After entering the details, press 'Save'
• Try to send a test email using 'Send Test Email'
  • If it shows 'Failed to send':
    • Click 'Authenticate' and log in using the account added as a “Send as” delegated member in step 3 to enable the token 
    • Try 'Send Test Email' again and once successfully received it is configured for use
• Whilst testing, you can disable/enable the 'Using Office 365 SMTP' to use either SMTP method

2a. Documents to receive — Lumiya configuration

There are two steps for receiving invoices or orders:

1. Company settings
2. Mailbox configuration

Company Settings

Only one company setting is necessary to configure this mailbox: ‘Invoice to Email’.

• Search for 'invoice to email' in the list
• Click ‘Add New’ if it’s not listed
• Add the email address
• Click ‘Save’

Mailbox Configuration

Note: To complete this, you may require access via an anonymous browser window, as the mailbox 'Open consent form' login would then not be confused with any current user login.

To complete the mailbox configuration:

• Proceed to the Intelligent Capture screen, either via Audit or Admin > Audit
• Select the mailboxes option from the top right
• Unlock on the box that pops up

• Enter your password and click 'Unlock'
• Click the edit option on an existing set-up or add details on the right to enter a new mailbox

• Select 'purchase invoice' or 'sales order' from the dropdown
• Enter the email address
• Check the 'Active' tick box
• Select the type of email from the dropdown: 
• After entry, click ‘Test’ to validate that the mailbox is correctly configured
• Depending on your selection, you may need to complete additional fields

Gmail:

• Enter the password

On-Premises Exchange:

• Complete the listed fields
  • Host
  • Port
  • Domain
  • Username
  • Password
  • Secret (If using MFA)

Office 365 (basic authentication)

• Complete the listed fields:
  • Domain
  • Username
  • Password

Office 365 (advanced authentication)

• Enter the following information:
  • Tenant ID
  • App ID
  • Secret
  • Domain (optional)
  • Username (optional)
  • Password (optional)

• To test the connection, click ‘Grant consent’
  • Note: This likely requires being from an incognito browser window, so the process requires a login

• To prepare the mailbox for automatic connection, this process will open a new tab/page prompting you to authenticate using the same username and password as entered on the configuration screen
• Once authenticated successfully, you'll see a page to verify the application
• Once selected, the page will go blank and can be closed
  • Note: If consent has already been granted or the account is already logged in, the page will skip the process and remain blank, at which point it can be closed
• Click 'Save' to save the configuration

You've now configured the purchase invoice or sales order mailbox.

2b. Modern Authentication – Oauth 2.0 Configuration WITH MFA - Client Pre-requisites

Email Accounts:

Lumiya can connect to an actual inbox with a license
Lumiya can also access a shared mailbox (with no license) via a delegated email/password of an account that does have a license and access to the mailbox.

Steps required:

Access the admin portal.

Browse to https://portal.azure.com and log in with an administrator account.

Follow the steps below (which can also be found in the link below).

https://learn.microsoft.com/en-us/exchange/client-developer/exchange-web-services/how-to-authenticate-an-ews-application-by-using-oauth

Step 1 – Register the application

• Select 'Identity' in the left-hand navigation
• Select app registrations under Applications
• Select new registration
• On the 'Register an Application' page, set the values as follows:
  • Name = Lumiya OCR Mailbox
  • Supported account types = Accounts in this organizational directory only (xxxxxxx only - Single tenant)
  • Redirect URI = “Public client (mobile & desktop)” with https://login.microsoftonline.com/common/oauth2/nativeclient
• Click 'Register'
• Copy the values of the application (client) ID and directory (tenant) ID and save them
  • You'll need them later

Step 2 – Configure authentication

• Select 'Manifest' in the left-hand navigation under 'Manage'
• Locate the “requiredResourceAccess” property in the manifest
• Add the following inside the square brackets ([]):

{

    "resourceAppId": "00000002-0000-0ff1-ce00-000000000000",

    "resourceAccess": [

        {

            "id": "dc890d15-9560-4a4c-9b7f-a736ec74ec40",

            "type": "Role"

        }

    ]

}

• Save
• Select 'API permissions' under 'Manage'
  • Confirm that the full_access_as_app permission is listed
• Select 'Grant admin consent for org' and accept the consent dialogue
• Select 'Certificates & Secrets' in the left-hand navigation under 'Manage'
• Select 'New client secret', enter a short description, and select 'Add'
• Copy the value of the newly added client secret and save it
  • You will need it later

Step 3 – Restrict the accounts enabled

• Once you've completed the above steps, all mailboxes within the tenant can be accessed via the app registration, which is not always desirable
• We advise following the steps at the following link to restrict access to mailboxes Lumiya should be able to connect to and download from:
  • https://learn.microsoft.com/en-us/graph/auth-limit-mailbox-access

Step 4 – Apply conditional access policies

• If required, conditional access policies can be applied to the registered application
  • From within the Entra Admin Portal under the Enterprise applications section, select the app and follow the menu 'Conditional Access' within the 'Security' section

• For IP addresses, please contact your consultant

Step 5 – Share details

• For us to link up your accounts, please provide the following, which can be done using https://onetimesecret.vision33.com/ 
  • Directory (tenant) ID
  • Application (client) ID
  • Secret
  • Email address to download from (one per company per document type)

Previous

Next