Hoxhunt button: Special - Distributed installation of Hoxhunt for Google Workspace (native Gmail add-on)

IMPORTANT: Hoxhunt has released a new Google Workspace Add-in for Gmail, which is the
recommended option for all new Hoxhunt customers. Read more:
Hoxhunt button: Distributed installation of the Google Workspace add-on
Please reach out to your Onboarding Manager before continuing with the installation
of the Native Gmail add-on.


Hoxhunt for Gmail add-on is not yet generally available through Google Marketplace. However, Hoxhunt's native Gmail add-on can be implemented as a Private Gmail App for the time being.

If you are interested in the Chrome implementation, please check this article.

Requirements for implementation

  • User with Google Administrator rights is needed to complete the setup

  • User must have basic knowledge and skills to operate in Google Admin Console

  • User must have access to Google Cloud Projects at https://console.cloud.google.com/.


  • Separate whitelisting in Google Workspace must be implemented before or after implementing the Private Gmail add-on. This allows Hoxhunt simulations to arrive safely and that they can be reported successfully.

  • Gmail might prevent you from reporting certain type of suspicious emails. This is a technical security restriction and it cannot be currently controlled by Hoxhunt or Google Workspace Admins.

  • These instructions expect you to use the Legacy Editor when accessing the two Hoxhunt projects via https://script.google.com/



Pre-task: Whitelist incoming Hoxhunt emails

A) Receive shared Google Cloud Projects

B) Set up a new Cloud Platform Project

D) Enable private Hoxhunt for Gmail add-on

E) Distribute Hoxhunt for Gmail add-on

F) Test your private Hoxhunt for Gmail add-on


A) Receive shared Google Cloud Projects

  1. Navigate to https://script.google.com/
  2. Switch to Shared with me folder and locate both Hoxhunt addon loader and Hoxhunt for Gmail.
  3. Click on Hoxhunt addon loader.
  4. Select File > Make a copy.

IMPORTANT: Your editor view should look like this:


If the layout doesn't match the instructions, please switch to the Legacy Editor.



B) Set up a new Cloud Platform Project

  1. Go to https://console.cloud.google.com.

  2. Next to the main title Google Cloud Platform, click Select a Project > Select from [organization name] > NEW PROJECT.

  3. Provide your new project a name Hoxhunt for Gmail and click CREATE.

  4. Navigate to APIs & Services > OAuth consent screen.
    TIP: If you are unable to locate it, user Search bar and look for "OAuth consent screen".

  5. In the OAuth consent screen section, tick Internal and click CREATE.

  6. Fill in data as follows:

    App name: Hoxhunt for Gmail
    User support email: support@hoxhunt.com or your own internal support address
    Application logo:
    Logo_shield.png (downloadable at the end of this article)

    Application homepage link: https://www.hoxhunt.com/
    Application Privacy Policy link: https://www.hoxhunt.com/
    Application Terms of Service link (Optional): leave empty

    Authorised domains: hoxhunt.com

    Developer contact information: support@hoxhunt.com


  8. In the Scopes section, click ADD OR REMOVE SCOPES.
  9. Scroll down to Manually add scopes, and paste in the following lines:

  10. click ADD TO TABLE and then click UPDATE.
  11. Click SAVE AND CONTINUE. No actions are needed on the Summary page.


  1. Click on Google Cloud Platform title at the top blue bar.
  2. Make a note of the Project number visible under Project info section.

  3. Switch back to your Copy of Hoxhunt addon loader tab and link it to your Cloud project by selecting Resources > Cloud Platform Project…
  4. Enter your Project number and click Set Project.
  5. Click Confirm and Close.


D) Enable private Hoxhunt for Gmail add-on

  1. While you have Copy of Hoxhunt addon loader open, select Publish > Deploy as add-on…

  2. If prompted, Click Accept. Publish an add-on dialog will appear.

  3. Instead of clicking Ok, click on Google Workspace Marketplace SDK link in the dialog.
    (You will be taken to Google Cloud Platform > APIs & Services > Dashboard > Google Workspace Marketplace SDK)

  4. Click ENABLE.

  5. In the navigation side bar, switch to App Configuration section.

  6. Under App integration, tick Google Workspace add-on checkbox. Deployment ID field will appear.

  7. Switch back to Copy of Hoxhunt addon loader tab.

  8. Select Publish > Deploy from manifest…

  9. Deployments dialog opens. Click Create. Fill in the following details:
    Deployment name: Hoxhunt for Gmail (MM-DD-YYYY)

  10. Click Save.

  11. In Deployments dialog, click Get ID next to Hoxhunt for Gmail (MM-DD-YYYY).

  12. Copy-paste the Deployment ID back to Deployment ID field.
    (Google Workspace Marketplace SDK > App Configuration > App integration > Google Workspace add-on)

    Do not click SAVE until you have completed step 16! App visibility setting will be otherwise locked and if you had it in wrong setting, you need to restart the implementation.

  13. Scroll down to Developer Links and fill in the following details:

    Application website URL: https://app.hoxhunt.com/
    Developer name:
    Hoxhunt Oy
    Developer website URL: https://www.hoxhunt.com/
    Developer email:

  14. Scroll down to Installation Settings and choose how Hoxhunt can be installed:
    Individual + Admin install (users are able to install Hoxhunt add-on on their own)
    Admin-only install (only Admins can control the installation)

  15. Scroll down to App Visibility and tick Private.

    Once you choose an app visibility option and save the App Configuration page, you can't change your selection later.

  16. Click Save.

  17. Switch to Store listing section.

  18. Under App Details, click on downward pointing arrow and enter following details:
    Language: English
    Application name: Hoxhunt for Gmail
    Short Description: Hoxhunt is an automated cyber training program that transforms the way your employees react and respond to the growing amount of phishing emails.
    Detailed Description: Hoxhunt is an automated cyber training program that transforms the way your employees react and respond to the growing amount of phishing emails.

  19. Click DONE.

  20. Set Category to Utilities.

  21. Scroll down to Graphics Assets and upload Application Icons and Screenshots from the materials package (downloadable at the end of this article):

    Application icons: icon_32x32.png, icon_48x48.png, icon_96x96.png, icon_128x128.png
    Application Card Banner: Banner_220x140.png
    Screenshots: 1_Stars.png, 2_User-dashboard.png, 3_Invitation start.png, 4_Onboarding 1.png, 5_Onboarding 2.png

  22. Scroll down to Support Links and fill in the data as follows:
    Terms of service URL: https://www.hoxhunt.com/
    Privacy policy URL: https://www.hoxhunt.com/
    Setup URL: leave empty
    Admin config URL: leave empty
    Support URL: https://support.hoxhunt.com/
    Deletion policy URL: leave empty
    Help URL: https://support.hoxhunt.com/
    Report issue URL: leave empty

  23. Under Distribution, tick All regions.

  24. Click Publish.

Hoxhunt is now available in your domain's Marketplace.


E) Distribute Hoxhunt for Gmail add-on

  1. Navigate to https://admin.google.com and select Apps > Google Workspace Marketplace Apps.

  2. At the top of the list, click Add app to domain install list
    TIP: you can also go directly to https://gsuite.google.com/marketplace/mydomainapps

  3. Search for “Hoxhunt” and click on Hoxhunt for Gmail.

  4. Click Domain install.

  5. Under Domain wide install dialog and click CONTINUE. Then select Turn ON for and select the OUs (operational units) you wish to install Hoxhunt add-on to, agree the terms and click ALLOW.

    Hoxhunt for Gmail has now been installed.

  6. Switch back to admin.google.com and navigate to Apps > Google Workspace Marketplace Apps. If you can’t see Hoxhunt for Gmail on the list yet, refresh the page.

TIP: If you want to change the availability scope afterwards, go to https://admin.google.com/ac/apps/gmail/marketplace/domaininstall, click Hoxhunt for Gmail and then select the Organisational units you want Hoxhunt add-on to be installed.


F) Test your private Hoxhunt for Gmail add-on

  1. Log in to Gmail.

  2. Open any email and click Hoxhunt button visible on the right-hand side.
    TIP: Make sure you have Side panel open.

  3. On first time, Hoxhunt for Gmail add-on will ask for authorization to access your email.

  4. Click AUTHORIZE ACCESS and enter your credentials.

  5. Click REPORT and follow given instructions.

This concludes the implementation.



Removing private Hoxhunt Gmail App

A) Disable private Hoxhunt Gmail App’s for all users

  1. Go to admin.google.com and navigate to Apps > Google Workspace Marketplace apps.

  2. Click Hoxhunt for Gmail in the apps list, select OFF for everyone and click SAVE.

Private Hoxhunt Gmail App is now uninstalled from all users.


B) Remove Hoxhunt for Gmail Cloud Project

  1. Go to console.cloud.google.com and you'll land on Dashboard/Home view.

  2. Click Hoxhunt for Gmail at the top-most blue bar.

  3. Click the kebab menu in the top-right corner and select Manage resources > Hoxhunt for Gmail and click DELETE.

  4. Enter the Project ID visible in the underlying view (“Hoxhunt for Gmail”) and click Shut down to complete removal.

Cloud Project will be removed by Google in the coming weeks.


C) Remove copy of Hoxhunt add-on loader

  1. Navigate to Google Drive.

  2. Remove your copy of Hoxhunt addon loader.

Hoxhunt will stop sharing Hoxhunt for Gmail and Hoxhunt addon loader in a moment.


Was this article helpful?

1 out of 1 found this helpful

Have more questions? Submit a request