Knowledge Base
  1. Home
  2. Knowledge Base
  3. Heroic Inbox Plugin Documentation

Heroic Inbox Plugin Documentation

This guide walks you through how to set up and configure the Heroic Inbox plugin.


To install Heroic Inbox plugin you will require a self-hosted WordPress version 5.1 or higher installation. You will need a Google Mail (Gmail) or Google Workspace account with the ability to activate the Gmail API.

You can install the plugin in a number of ways:

  • From Zip File: In the WordPress admin panel navigate to Plugins > Add New, select the ‘Upload’ and browse to the zipped plugin file, and hit install now.
  • FTP Upload: Using your FTP program upload the un-zipped plugin folder into the /wp-content/plugins/ folder of your WordPress installation.

Once the plugin has been installed, you need to activate it. Go to Plugins > Installed Plugins and activate Heroic Inbox.

Welcome Screen

Upon plugin activation, you will automatically be sent to the Heroic Inbox setup assistant page.

Enter your license key

To enable automatic updates and support enter your license key when prompted, you can find this in your purchase email or HeroThemes Account area.

Setting the Heroic Inbox license key

Add a Mailbox

Heroic Inbox allows you to use add both IMAP/SMTP mailboxes and Gmail mailboxes.

IMAP/SMTP Mailboxes

Adding a regular email account, such as those offered by a web host service provider or dedicated email providers.

Most email service providers are supported. The actual configuration of IMAP and SMTP varies depending on provider, who can provide further guidance on the required settings enabling access from 3rd party email clients.

Gmail Mailboxes

You will first need to create a Google App for Heroic Inbox which will handle the sending and receiving of mail on behalf of the plugin.

To access a specific Gmail inbox, click Select Mailbox and follow the steps. Check you are comfortable with the access granted, remember this access is only granted to the App you created and manage in your Google App. Access can be revoked at any time.

Allow your Heroic Inbox project to access email

When you click Allow, you’ll be sent back to the Heroic Inbox setup assistant, using the callback URL entered as the Authorized redirect URI in the App creation process.

Final Steps

This will complete the mailbox setup and you’ll see the Heroic Inbox is Ready screen.

You can test the Mailbox configuration by clicking Send Test Mail to send a test message to yourself from your site via the Gmail API. You should be able to see the result in your Gmail. You can then click Get Welcome Mail.

Ready to use click Send Test Message and Get Welcome Mail to test the mailbox

Note that Heroic Inbox does not import prior messages, only messages received since setup are available in your Heroic Inbox mailbox.

Mailbox Basics

The Dashboard

The mailbox dashboard can be accessed from Heroic Inbox > Dashboard.

It lists the current mailboxes and the messages in each box:-

Inbox – new (open) and unassigned messages

Mine – open messages assigned to the current logged in user

Assigned – open messages assigned to other users

Closed – all closed messages

Messages are organised into threads and can have a number of states including:-

Open – new messages that need attention

Pending – messages that are blocked but still need attention

Closed – messages that are dealt with and closed

The Dashboard View

Mailbox View

Clicking on any of the mailbox filters will show the conversations in that mailbox, you can change the filter at any time by clicking on the carat next to the filter name in the breadcrumb at the top of the screen.

The Inbox view

Select a conversation to view the messages in that conversation and compose replies.

Conversation Basics

From a conversation you can perform all the main interactions with the conversations, review the thread and take actions.

The main conversation screen

Conversation Thread

In the center of the screen is the conversation thread, showing the message exchange between the contact and the mailbox users (staff). You can see messages from the contact, replies and notes. Notes are not visible to the contact, only to mailbox users.

Conversation Meta

Just above the thread view is the subject of the conversation, along with the tags on the right.

On the right hand side of the screen is the contact information and previous conversations with that contact. Clicking on a previous conversation brings up a preview.

Conversation Actions

At the top of the screen, beneath the breadcrumbs are the Conversation Actions. These include, replying to the contact, adding a note, changing the conversation status, assigning the conversation to another mailbox user and tagging the conversation.

On the right of the conversations actions is the current conversation status and the currently assigned user (gr)avatar.

Replying and Adding Notes

Click Reply or Add Note in the conversation and the editor will appear where you can compose a message.

Clicking on the Send Reply drop down will allow you to schedule a reply to be sent at a later date, otherwise it will be sent instantly.

Composing a reply

Composing Messages

To start a new message click on the Compose button in the top-right of the screen from the Mailbox View. This will allow you to create new mail from the current mailbox.

On the mail compose screen, enter the recipient address. For new contacts, use the email address. For existing contacts you can use the email address or contact name. Contact details and previous conversations will be displayed on the right.

Enter a Subject, click again to edit.

You can then enter the message in the editor, once done click Send to send the message.

Message compose screen


When messages arrive in Heroic Inbox, any attachments are imported into a protected folder within your WordPress uploads folder, these are displayed in the message. It’s important you check these attachments cannot be accessed directly.

It’s possible to view these attachments in the admin, providing the user can view the mailbox.

To attach an attachment to a message, click the paperclip button above the editor.

Adding attachments to a message

Heroic Inbox Settings

This screen controls the global Heroic Inbox settings, it can be accessed from Heroic Inbox > Settings. From here the individual mailbox settings can be accessed via the Mailboxes tab.

General Settings

The current version number and a link to the Debug screen can be found at the bottom of the settings screen.

Activating Automated Updates and Support

If you have not previously entered a license key for automatic updates and support, you can do so from the License Key section in the General Settings tab.

Google API Settings

The Gmail Authentication section displays the Google Gmail API authentication status. This should be green and active, if it’s red, it can be regenerated using the setup assistant.

Setup Assistant

The Setup Assistant / Wizard can be launched from the Settings General tab. It guides through the creation of the Google Gmail API project, mailbox creation and linking and testing new mailboxes.

Mailboxes Tab

The mailboxes tab lists the current mailboxes that are active, you can add a New Mailbox and select a Gmail account to link to the new mailbox here.

Mailbox Settings

Each mailbox has a number of different options than can be controlled via the Settings tabs.

Mailbox Settings Tab


The mailbox display Name and Description can be set from the General Tab. The Check Interval sets the minimum interval that the inbox will be checked for new messages and import these into Heroic Inbox. This can also be performed manually by clicking Get Mail Now. The Disable Powered By signature removes the Powered By Heroic Inbox signature when checked.

Mailbox General Settings

Email Connection

This tab displays the current authorization code for the mailbox, if the fetch fails with an authorization error, you can regenerate the authentication and obtain a new code by clicking the Regenerate Auth Code button, repeating the mailbox authorization process and entering the newly generated code.

Mailbox Email Connection Settings


The users section can be used to assign user access to the mailbox. Currently two user levels are available – User and Admin. When the mailbox is setup via the setup assistant the current user is assigned Admin and User privileges. New Users can then be assigned using the Add User button.

Mailbox Users Settings

Auto Responder

An auto-responder can be enabled for each mailbox to send an automatic reply when a new message is received for each new thread. Check Enable Auto Responder to activate the auto reply functionality.

Mailbox Auto Responder Settings

Saved Replies

Saved replies can be used to speed up reply composition, the Saved Replies available to this mailbox. Click New Saved Reply to compose a new saved reply for use with this mailbox.

Mailbox Saved Replies Settings

Current Limitations

The current focus of the plugin on message flow and simple operations, while key functionality is tested and reviewed. There are several known limitations including:-

Email attachments are not handled. Messages containing attachments will be empty. Plugin now includes email attachment support for sent / received messages as of v1.2.0

Conversations cannot be started from Heroic Inbox. You can currently only reply to incoming messages. Plugin now includes compose mail functionality as of v1.1.0.

There is no import functionality. Only new messages will be imported from when Heroic Inbox

Only works with Gmail and Google Workspace email accounts. SMTP, POP, exchange etc are not supported. Plugin now supports IMAP / SMTP mail servers as of v1.5.0.

If you encounter issues, or require further support, please contact the support team who can provide assistance.

Was this article helpful?