Email Approval Configuration Guide

this guide explains how to configure activate to process approvals via email using exchange web services (ews) or via graph in 8 4+ it covers requirements, configuration steps, how approval messages are parsed and validated, and recommended best practices ews online is being deprecated, target for shutdown is october 2026 activate 8 4 includes the capability to poll mailboxes via graph instead of ews overview activate can monitor an exchange mailbox to detect and process approval responses sent by approvers via email why use email approvals? email approvals allow approvers to approve or decline requests directly from their email client, on desktop or mobile, without logging in to the activate web portal this helps streamline approval workflows, reduce response times, and improve the overall experience for approvers who work primarily from email this capability is implemented using exchange web services (on premises only) or graph (exo only) requirements exchange server compatibility functionality applies to streaming subscription monitoring (near real time) ews only polling (interval based) graph or ews on premises exchange 2010 sp2 or later supports streaming subscriptions via ews where streaming subscriptions are not available, activate falls back to polling the mailbox at regular intervals exchange online is supported using graph with oauth authentication (configured via the exchange server resource and connection provider) mailbox requirements a dedicated mailbox is strongly recommended for email approvals the mailbox must belong to an active (non disabled) user account not be a shared mailbox be correctly licensed (exchange online plan 1 / e1 or higher) allow access via exchange web services or graph configuration configure the exchange server resource path //resources/exchange servers parameter description webserviceurl url of the exchange web services endpoint oauthenabled set to true for exchange online connectas reference to an entra id connection provider (for example =//resources/activedirectory/external directories/azure/connection) configure the email resource path //resources/configuration/email parameter description emailaddress email address of the mailbox used for approvals if not set, activate attempts to derive it from connectas, then falls back to the current user email address enablemailapprovals set to true to enable email approval processing exchangeserver path to the exchange server resource (for example //resources/exchange servers/exchangeonline or your on premises server resource) connectas optional credentials used to access the mailbox for exchange online this is typically handled via oauth in the exchange server resource for on premises exchange this can be a network credential that has full access to the mailbox username / password deprecated use connectas instead disablesubscription optional set to true to use polling instead of streaming subscription monitoring (default false when supported by the exchange server resource) only applies to ews pollinterval optional interval in minutes subscriptiontimeout optional streaming subscription reconnect period in minutes (default 30) only applies to ews trace optional activate side logging verbosity (default 0) tracewebservice optional ews tracing verbosity (default 0) options optional mail approval behaviour flags (for example alwaysreply) validauthtypes optional comma or semicolon separated list of accepted x ms exchange organization authas values (default internal) emailfilters optional one or more xml filter parameters that are merged at runtime mailbox access rights on premises exchange grant full access permissions on the approval mailbox to the identity that will connect to exchange common approaches run activate orchestrator under a service account that has full access to the mailbox set connectas (network credential) to a user that has full access to the mailbox exchange online for exchange online, mailbox access is provided through an azure application using oauth authentication the application requires the mail read and mail send application permissions we also recommend implementing an application access policy for approval mailboxes (azure ad / exchange online) docid\ ljn8epz6kjm7qnvb3r5ok to restrict the application's access to only the required approval mailboxes, following the principle of least privilege how email approvals work activate processes each new email message using a defined sequence of parsing and validation steps messages that fail validation are rejected and typically moved to deleted items with an error prefix added to the subject in most cases, an error response email is also sent back to the sender authentication check incoming emails must be authenticated and include the x ms exchange organization authas header by default, activate only accepts messages where the header value matches internal this can be broadened or changed using the validauthtypes parameter anonymous or unauthenticated messages, such as those sent via smtp relays, are rejected error message returned "this message cannot be accepted for approvals as it did not come from a secure client please use an outlook or activesync client to send this message " job number matching the email subject must contain a job number in the following format \[#1234] activate scans for the \[# marker and reads the digits that follow it if the job number is missing or invalid, one of the following errors is returned "this message does not appear to contain a valid job id in the subject " "job number {0} is invalid " user validation the sender’s email address must match a valid active directory user via the mail attribute if the sender is a linked mailbox account (for example, msexchmasteraccountsid is present), activate resolves the master account and uses that identity for authorisation checks if the user cannot be resolved, the following error is returned "sorry but i was unable to match the email address \[{0}] to a valid user please logon to the web portal to perform this action " command parsing activate supports commands provided either in the email body (first line), or in the subject after the job marker, using ] (for example \[#1234] approve) if a command is provided in the subject, the body is treated as the reason or message text supported commands approve \[optional message] decline \[message required] reply \[optional message] (respond to an information request) request \[optional message] (request more information) if the command is not recognised, the following error is returned "sorry i did not understand "{0}" please specify a command as the first line in your email (for example, approve) or logon to the web portal to perform this action " authorisation check activate verifies that there is a waiting approval action on the job that the sender is permitted to action the sender must match either the action user or an override user for the approval action if the sender is explicitly denied for the approval action, email approvals are rejected if the approval action does not allow email approvals (for example, the approval requires additional input), activate rejects the request and instructs the user to use the web portal instead possible errors include "sorry but you cannot perform actions on this job at this time the job may have been approved or declined by another user " "sorry but you cannot action this request please logon to the web portal to view more information about this action " "sorry but you cannot perform actions on this job via email as further information is required please use the web portal instead " approval completion if all validation steps succeed, activate executes the action against the waiting approval on the job by default, successful actions do not generate a confirmation email the processed message is moved to deleted items if the options parameter includes alwaysreply, activate sends a confirmation response (for example, "thank you your action has been accepted ") and also moves the original message to deleted items errors always generate an email response (when replies are allowed) and the original message is moved to deleted items with an error prefix added to the subject filtering emails (optional) to avoid unnecessary processing of non actionable messages (for example automatic replies or known unwanted senders), filtering can be configured using one or more emailfilters parameters each emailfilters value is an xml fragment that contributes \<mail> filter nodes activate merges these fragments at runtime if no emailfilters parameters are configured, activate applies built in filters for common auto replies using headers such as auto submitted , x autoreply , and x autorespond excluding specific senders or content in addition to the default automatic reply suppression, activate can be configured to explicitly ignore messages from specific senders or messages containing known subject or body content this is commonly used to implement a “do not reply” list for email approvals filtering rules are case insensitive and can be based on sender email address subject content message body content it is strongly recommended that the default automatic reply filters are retained when adding custom rules example configuration (ignore automatic replies and specific senders or content) \<emailfilters> \<ignore> \<sender>automatic reply \</sender> \<sender>cameron\@activatelive com\</sender> \<subject>my subject is spam\</subject> \<body>my body is spam\</body> \</ignore> \</emailfilters> if emailfilters parameters are manually configured, only the defined rules are applied review and test filter behaviour carefully when making changes, especially in production environments logging and debugging log file location \[installdir]/logfiles/activate exchangepoll log common entries include startup and mailbox identity (including whether subscriptions are enabled) connection and reconnect attempts polling or synchronisation errors sample log entry starting monitoring //resources/exchange servers/avmtestexch01, subscription=true best practices use a dedicated mailbox exclusively for approvals to avoid processing unrelated emails prefer streaming subscriptions where available for faster processing use polling only when subscriptions are not supported or when required by environment constraints configure validauthtypes to match your exchange environment keep it narrow unless you have a specific reason to broaden it use emailfilters to suppress auto replies and known noisy senders, especially when external systems are involved if you need acknowledgements for successful actions, enable options = alwaysreply otherwise, leave it disabled to reduce mailbox chatter when using decline, ensure the sender includes a reason in the message text, as declines require a reason restart the activate orchestrator service after configuration changes