Mail Archive Agent


WorkBook includes an agent named: “Mail Archive Agent”
The Mail Archive Agent allows you to automatically save imported emails directly to a Job based on the Job Number in the email Subject.


  • WorkBook Version 8.3.5 or newer.
  • An IMAP Compatible mail account.
    • Username
    • Password
    • Server Address
    • Port number
  • A WorkBook account that will be used by the Agent.
  • A WorkBook account with System Administrator privileges.


  1. Login to WorkBook using an account that has System Administrator privileges.
  2. Navigate to Settings -> Agent setup
  3. Click the “New” button and select “Mail Archive Agent”
  4. Select your newly created Agent
  5. Select the tab “Parameter”
  6. Fill out the parameters accordingly
    Name Description Example
    WorkBook Web Address This should be the address to your WorkBook installation, you can find this by looking in the top of your Web Browser where the Address is displayed
    User login This should be the WorkBook Account login that will be used by the Agent admin
    Password This should be the WorkBook Account password that will be used by the Agent ****
    IMAP Server Address Full address to your IMAP Server including port and prefixed with ssl:// if the server uses SSL ssl://myimapserver:993
    IMAP User Login Username used by the IMAP Account, this will often be the full email address or mydomain\myaccount
    IMAP Password Password used by the IMAP Account *******
    IMAP Folder Folder where WorkBook locates the incoming emails, on most mail servers it will be “INBOX” INBOX
    Subject regex This sequence tells WorkBook to look for a number to correspond to within the system. Leave this as-is. (?:^|\s)[0-9]+(?:$|\s)
    Archive to ref type When this reference type is set to 1, WorkBook knows to search for a Job Number using the Subject regex above. Leave this as-is.  1
  7. Select the tab “Scheduling”
  8. Setup a schedule
    • Normally we recommend a schedule to run every 2-5 minutes.

Example IMAP Configurations

This is basic IMAP information on some of the most common IMAP providers.

Gmail and Google Apps

IMAP Server Address ssl://
IMAP User Login or username@domain.tld
IMAP User Password ******

Get started with IMAP and POP3 – Gmail Help
Enable IMAP and POP for Google Apps

Office 365

IMAP Server Address ssl://
IMAP User Login username@domain.tld
IMAP User Password ******

Settings for POP and IMAP access for Office 365 for business or Microsoft Exchange accounts


The error messages provided by WorkBook may be unclear sometimes, if you wish a more details error try and use the Microsoft Connectivity Analyzer.


As mentioned above, this agent cannot be run on a per-user basis. If you wish to have all emails with Job numbers in the title automatically imported into WorkBook and saved to their respective jobs, consider creating a new email address for the sole purpose of importing these emails, i.e., and BCCing the account on the pertinent correspondences to ensure they are brought into WorkBook accordingly.

Was this article helpful? Useful Useless 0/0 found this article helpful.