Cloudflare Docs
Cloud Email Security (formerly Area 1)
Edit this page
Give us feedback
Set theme to dark (⇧+D)

Retraction guide for Gmail

Email workflow for retracting emails with Google Gmail

In this tutorial you will learn how to set up email retraction for Gmail.

​​ 1. Configure project and service account in Google Cloud Platform

For Cloud Email Security to be able to retract messages from Gmail inboxes, you first need to create a service account in a Google Cloud Platform (GCP) project.

  1. Access the Google Cloud Console. From the Dashboard, select CREATE PROJECT.

    Select Create project to start your new project
  2. Provide the details for the new project, and select CREATE to start your new project.

    Fill in the details from your organizations
  3. Once the new project has been created, the GCP console will automatically redirect you to the Project console. If not, you can use the Project selector to change to the project you created.

    If you need, use Project selector to choose the project you created in the previous step
  4. In the Getting Started card, select Explore and enable APIs to access the APIs and services configuration console.

    Find the Getting started card, and select Explore and enable APIs
  5. Select ENABLE APIS AND SERVICES to open the API Library.

    Enable APIs and services
  6. You will need to enable the Admin SDK API and the Gmail API. On the API Library, locate the Google Workspace section. Then, select View All to access all the available APIs for Google Workspace.

    Find the View all link to access the Admin SDK API and Gmail API
  7. Select Admin SDK API.

    Select the SDK API
  8. Select Enable to activate the Admin SDK API.

    Select Enable to enable the SDK API
  9. Return to the Google Workspace API library, and select the Gmail API.

    Select the Gmail API
  10. Select ENABLE to activate the Gmail API.

    Select Enable to enable the Gmail API
  11. You will now create a service account to use the API. From the Gmail API console, select Credentials.

    Select Credentials to create a service account
  12. Select CREATE CREDENTIALS > Service account.

    Select Create credentials followed by Service account
  13. In Service account details provide the following information:

    • Service account name: Message Retraction Service Account
    • Service account ID: This value is automatically generated.
    • Service account description: A description for this service. For example, Cloud Email Security Message Retraction

    Select CREATE AND CONTINUE when you are done.

    Provide the details to create the service account
  14. In Grant this service account access to project, select the Select a role drop-down menu. Then, select Project on the left column, and Owner on the right column.

    Find the project owner options, in the Grant this service account access to project section
  15. Once the role is assigned, select DONE to complete the setup.

    Select the Done button to complete the setup
  16. Once the role assignment has been saved, you will return to the API credential configuration console. In Service Accounts, select the newly-created service account to configure the domain-wide delegation.

    Select your newly-created service account to continue
  17. In Details, take note of the Unique ID. Then, select SHOW ADVANCED SETTINGS.

    Take note of the Unique ID code, and then select Show advanced settings
  1. Select VIEW GOOGLE WORKSPACE ADMIN CONSOLE to configure the domain-wide delegation. This will open a new window to the Google admin console.

    Select View Google Workspace Admin Console to configure the domain-wide delegation
  2. Go to Security > Access and data control > API controls.

    Go to Security, Access and data controls, and select API controls
  3. Find the Domain wide delegation section, and select MANAGE DOMAIN WIDE DELEGATION.

    Select Manage domain wide delegation
  4. Select Add new to add a new client ID.

    Select Add new
  5. In Add a new client ID, enter the following information:

    • Client ID: Enter your client ID. This is the Unique ID value you saved in step 17.
    • OAuth scopes: Enter the following information (the input field accepts comma separated values):
    https://www.googleapis.com/auth/admin.directory.user.readonly, https://www.googleapis.com/auth/admin.directory.group.readonly, https://www.googleapis.com/auth/admin.directory.user.alias.readonly, https://www.googleapis.com/auth/gmail.labels, https://mail.google.com/

    Select AUTHORIZE when you are finished.

    Enter the required information
  6. Return to the Google Cloud Platform (GCP) console, and select IAM & Admin > Service Accounts to return to the service account screen.

    Select Service accounts
  7. You need to create an API key in the Service account configuration panel. Select the three dots button to open the menu. Then, select Manage keys:

    Select the three dots menu, and then select Manage Keys
  8. In the Keys configuration panel, select ADD KEY > Create new key.

    Select Add Key and then Create new key
  9. In Key type select JSON as the format to create the private key. Then, select CREATE.

    Select JSON as the key type

​​ 2. Share the service account JSON key with Cloud Email Security

You have to upload the private key generated in the previous step to Cloud Email Security. This is needed to execute retractions on your Gmail inboxes.

  1. Log in to the Cloud Email Security dashboard, and select Settings (the gear icon).

  2. Go to Email Configuration > RETRACT SETTINGS > Authorize Gmail.

    Go to Authorize Gmail in your Cloud Email Security dashboard
  3. Select New Authorization and configure the following settings:

    • Select AUTHORIZATION DATA (JWT), and find and upload your JSON private key.
    • Under Domains, specify which domain this private key belongs to.
    • Select Save to save the configuration.

    Select New authorization and configure its settings

​​ 3. Configure auto-retraction actions in Cloud Email Security

You can set up auto-retraction to automatically move messages matching certain dispositions to specific folders within a user’s mailbox.

To set up automatic retraction:

  1. Log in to the Cloud Email Security dashboard.

  2. Go to Settings (the gear icon).

  3. On Email Configuration, go to Retract Settings > Auto-Retract.

  4. Select Edit.

  5. For each disposition, choose which folder the message should be sent to:

    • No Action: Do not move the message.
    • Junk Email: Sends the message to the junk or spam email folder.
    • Trash: Sends the message to the trash or deleted items email folder.
    • Soft Delete — user recoverable (Microsoft only): Sends the message to the user’s Deleted Items folder. Messages can be recovered by the user.
    • Hard Delete — admin recoverable: Completely deletes messages from a user’s inbox. Google Gmail messages cannot be recovered, even by the admin.
  6. Select Update Auto-retract Settings.

​​ Post delivery retractions for new threats

Cloud Email Security is continuously gathering new information about phishing campaigns. Users might have email messages in their inboxes that were scanned by Cloud Email Security but not retracted initially because, at the time of scan, these email messages had not been identified as a threat. To mitigate risk, Cloud Email Security offers you tools to re-evaluate email messages at a fixed time interval based on knowledge Cloudflare may have acquired since initial delivery. Any email messages that fit this new threat knowledge will be retracted.

You can enable two options:

  • Post Delivery Response: Cloud Email Security will continue to re-evaluate emails already delivered to your users’ inboxes at a fixed time interval in search for phishing sites or campaigns not previously known to Cloudflare. If any email messages fitting these new criteria are found, Cloud Email Security retracts them.
  • Phish Submission Response: Cloud Email Security will retract emails already delivered that are reported by your users as phishing, and are found to be malicious by Cloud Email Security. Retraction will occur according to your configuration.

​​ 4. Adjust the hop count in Cloud Email Security

Since Cloud Email Security is not configured as the MX record for your domains, you will need to adjust Area 1’s position (hop count) relative to Area 1’s position in the email processing order.

  1. Log in to the Cloud Email Security dashboard, and select Settings (the gear icon).

  2. Go to Email Configuration > DOMAINS & ROUTING.

  3. Select the three-dots menu on the domain you want to verify the position, and then select Edit.

    Go to Domain to verify Cloud Email Security’s hop position
  4. For standalone Gmail only deployments, the value should be set to 2. If it is not, adjust the Hops count to 2, and select Update Domain.

    Go to Domain to verify Cloud Email Security’s hop position

​​ 5. Configure BCC rule in Google Workspaces

You must send copies of inbound email messages to Cloud Email Security for inspection, so that Cloud Email Security can automatically retract messages. Messages can be sent to Cloud Email Security using a BCC compliance rule. Refer to the steps below to learn how to set this up. Automatic retraction is not available when Cloud Email Security is deployed as MX.

  1. In the Admin console, go to Menu > Apps > Google Workspace > Gmail > Compliance.

    Select the compliance option
  2. Scroll to Content Compliance and select CONFIGURE.

    Select the configure option
  3. Add a Content Compliance filter and name it Area 1 - BCC.

  4. In Email messages to affect, select Inbound.

    Choose inbound as the messages to affect
  5. Select the recipients that you want to send emails to Area 1 via BCC:

    1. Select Add to configure the expression.
    2. Select Advanced content match.
      1. In Location, select Headers + Body from the dropdown.
      2. In Match type select Matches regex.
      3. In Regexp input .*. You can customize the regex as needed and test within the admin page or on sites like https://regexr.com/.
      4. Select SAVE.

    Configure expressions
  6. In If the above expressions match, do the following, make the following changes:

    1. In Also deliver to select Add more recipients.

      1. Under Recipients select Add.
      2. Change the setting to Advanced.
      3. In Envelope recipient select Change envelope recipient.
      4. In Replace recipient add the recipient BCC address. For example, <customer_name>@journaling.mxrecord.io. This address is specific to each customer tenant and can be found in your Portal.
      1. Make sure that in Spam and delivery options > Do not deliver spam to this recipient is not checked.
      2. Under Headers select Add X-Gm-Spam and X-Gm-Phishy headers.
      3. Select SAVE.

    Configure recipients

    Configure headers
  7. Scroll down and select Show options.

    1. Under Account types to affect select Groups.
    2. Select SAVE.

    Configure groups

​​ Geographic locations

Select from the following BCC addresses to process email in the correct geographic location.

Host
LocationNote
<customer_name>@journaling.mxrecord.ioUSBest option to ensure all email traffic processing happens US data centers.
<customer_name>@journaling.mailstream-eu-primary.mxrecord.ioEUBest option to ensure all email traffic processing happens in Germany, with fallback to US data centers.
<customer_name>@journaling.mailstream-eu1.mxrecord.ioEUBest option to ensure all email traffic processing happens within the EU without fallback to US data centers.
<customer_name>@journaling.mailstream-bom.mxrecord.mxIndiaBest option to ensure all email traffic processing happens within India.
<customer_name>@journaling.mailstream-india-primary.mxrecord.mxIndiaSame as mailstream-bom.mxrecord.mx, with fallback to US data centers.
<customer_name>@journaling.mailstream-asia.mxrecord.mxIndiaBest option for companies with a broader Asia presence.
<customer_name>@journaling.mailstream-syd.area1.cloudflare.netAustralia / New ZealandBest option to ensure all email traffic processing happens within Australia.
<customer_name>@journaling.mailstream-australia.area1.cloudflare.netAustralia / New ZealandBest option to ensure all email traffic processing happens in Australia, with India and US data centers as backup.

​​ 6. Manual message retraction

When retraction is enabled, you can manually retract messages that were not automatically retracted.

  1. Log in to the Cloud Email Security (formerly Area 1) dashboard.

  2. Select the search bar and enter the search parameters to find the emails you are looking for.

  3. To retract a single message, select Retract. To retract multiple messages, first select the checkboxes on the messages you want to retract. Then, select Retract.

  4. Choose where you want to retract the message to, and select Retract message.

    Choose your retraction destination
  5. If the retraction was successful, there will be positive confirmation on Cloud Email Security’s dashboard.