Working With One-Click Message Pull

Created by Nadav Shenker, Modified on Wed, 29 Mar, 2023 at 3:11 PM by Yves Lacombe

About One-Click Message Pull

This optional feature, available in environments with Business+, Advanced+ or Professional+ licenses, allows administrators and authorized users to pull, from a user's Microsoft 365 mailbox, any emails that are suspected of being malicious or otherwise undesirable. If necessary, for example if the email is determined to be legitimate,  the administrator can restore the message to the user's mailbox.

Pulled messages have the status of "Delivered (Mail Retracted)".  


Also called mesage revocation or message revoke


Note that this feature applies only to domains that are within the Azure tenant and does not remove messages from the Essentials email archive.


Use of One-Click Message Pull is logged, with an entry indicating what action was taken and who took it.

The functions described here can be performed only by someone with Microsoft 365 administrator privileges.

Granting Administrator Access To One-Click Message Pull

Do one of the following:

  • if your environment does not use the Azure User Sync feature, create an App registration in Azure
  • If your environment does use the Azure User Sync feature, update the existing App registration

Instructions for both options are provided below.

Creating An App Registration In Azure

  1. Login to your Microsoft Azure portal as an admin user through https://aad.portal.azure.com
  2. Click Azure Active Directory > App Registrations > + New Registration.
  3. Enter a name for the application (e.g. "Proofpoint Essentials One-Click Message Pull").
  4. Under Supported account types leave the default of Accounts in this organizational directory only (COMPANY NAME).
  5. Under the Redirect URI (optional), leave the default of Web and enter the appropriate Proofpoint Essentials interface URL (US1, US2, US3, US4, US5, or EU1); e.g. https://us1.proofpointessentials.com or https://us3.proofpointessentials.com, etc.
  6. Click Register. You can now view the app in the App Registrations view.
  7. Copy your Application ID for future use as the Application ID in Proofpoint Essentials. 
  1. In the Application ID you just created, click API Permissions > Add a permission. Select Microsoft APIs and then click Microsoft Graph.
  2. Click Add a permission > Application Permissions and ensure that the Mail appplication permission "Mail.ReadWrite (Read and write mail in all mailboxes)" is checked.
  3. Click Add Permissions (at the bottom) and select Grant Admin Consent for <Company Name>.
  4. Click Yes (at the top of the page), then click Certificates and Secrets > + New Client Secret.
  5. Enter a Key Description, e.g. "Proofpoint Essentials One-Click Message Pull".
  6. Select a duration for the key (that is, the date on which the key expires).
  7. Click Add, then Save. The secret value is shown, along with other information:
    • the secret value is shown in the Client Secret Key field - be sure to copy the value, as you will not be able to retrieve it after saving the page
    • the Application ID needed to complete the credentials is shown in the Proofpoint field Application (client) ID in the Overview area inside the connection
      The Value will be displayed when you save the changes. Copy down the Value field, as you will NOT be able to retrieve it after leaving the page. The Value (in Azure AD page) will be put into the Client Secret Key field in Proofpoint Azure Sync pageYou will get the Application ID needed to complete the credentials in the Proofpoint field Application (client) ID from the Overview area inside the connection. 
  8. Important: Copy the contents of the Value field and store the value in a secure location. After leaving the page, you cannot retrieve it. The Value will be put into the Client Secret Key field in Proofpoint Azure Sync pageYou will get the Application ID needed to complete the credentials in the Proofpoint field Application (client) ID from the Overview area inside the connection. 

clipboard_e635594ee5667035339548f266842d0a7.png

The Value will be displayed when you save the changes. Copy down the Value field, as you will NOT be able to retrieve it after leaving the page. The Value (in Azure AD page) will be put into the Client Secret Key field in Proofpoint Azure Sync pageYou will get the Application ID needed to complete the credentials in the Proofpoint field Application (client) ID from the Overview area inside the connection. 

Important: This key will expire on the defined expiry date at the end of the selected duration period. After that period of time a new secret key must be generated.




Updating Existing App Registration In Azure


  1. Login to your Microsoft Azure portal (https://aad.portal.azure.com) as an admin user
  2. Click Azure Active Directory > App Registrations
  3. Select the exiting Proofpoint Essentials app registration (e.g. Proofpoint Essentials Azure Sync).
  4. In the Application ID, navigate to API Permissions > Add a permission and then, on the Request API permissions page, click the Microsoft Graph box.
  1. Choose Application Permissions and then add the "Mail.ReadWrite (Read and write mail in all mailboxes)" permission:
  2. Click Add Permissions (at the bottom of the page), then click Grant Admin Consent for <Company Name>.
  3. Scroll to the top of the page and click Yes.




Configuring Azure In The Proofpoint Essentials Interface

  1. Log into your Proofpoint Essentials interface (e.g. https://us1.proofpointessentials.com). 
  2. Click Administration > User Management > Import & Sync > Azure Active Directory. 
  3. Enter the following information:
    • for Primary Domain, enter the primary domain associated with your newly-created M365 Azure web application
    • for Client ID, enter the unique identifier generated when the web application was created
    • for Secret ID, enter the secret value generated when the secret key was created  
  4. Leave all options under What to Sync, How to sync and Groups unchecked.
  5. Set the sync frequency to never.
  6. Click Save.

Enabling One-Click Message Pull Feature

On the Features page, check Enable One Click Removal, then click Save.


Performing A One-Click Message Pull

Note that pulled messages will remain visible to administrators in the admin logs.

Search for and select the message(s) to be pulled, using either the All Users Log or the detailed email log entry for a message. Select the message(s), then click Retract from Mailbox

The selected messages are removed and their status changes to "Delivered (Mail Retracted)". 

If the selected message cannot be pulled, for example, it has been deleted, an informative message is shown. 

To restore the message, click Restore to Mailbox.


Identifying And Remediating A False Negative

In the email log, locate the message to be remediated. Click the three vertical dots and then, on the Detailed Log Entry screen, click Report as False Negative, acknowledge the message content, click report and then click Retract from Mailbox


Restoring A Pulled Message

In the email log, locate the message. Click the three vertical dots and then, in the Detailed Log Entry screen, click Restore to Mailbox. The message is restored and its status changes to "Delivered".  Note restoring a message modifies the timestamp to message restore time.