Email Approval Configuration Guide

this guide explains how to configure activate to process approvals via email using exchange web services (ews) 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 is developing a change to use graph for polling instead, expected q2 2026 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 (ews) and supports both exchange online and on premises exchange environments requirements exchange server compatibility activate supports two monitoring approaches streaming subscription monitoring (near real time) polling (interval based) 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 ews 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 configuration configure the exchange server resource path //resources/exchange servers true 330,331left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type configure the email resource path //resources/configuration/email true 330,331left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type 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 typically granted to the activate application via ews oauth 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