Introduction
CiviPlus can automatically retrieve email from a specified Gmail mailbox and file it as an email activity against contacts of type Individual or Organisation corresponding to the sender and recipients of the email (it can also file the email activity against an existing Case).
Depending on configuration, new individual contacts can be created for emails from addresses of individuals or organisations that do not currently exist in your CiviPlus database.
This integration can cover both:
Inbound email received into your Gmail mailbox(es).
Outbound emails not from CiviPlus, i.e. correspondence that you (a CiviPlus User) have sent from your own Gmail mailbox (not from CiviMail)
Example activity created from an inbound email:
Example activity created from an outbound email:
Using “Email-to-activity processing” always requires you to have an email account either in use already or set up specifically for CiviPlus to connect to. CiviPlus will not create any new inboxes in your email system by itself.
Note: The email account mentioned above should not be confused with the ones you may enter in CiviPlus as FROM email addresses. These can be used as addresses to show on emails when sending from within CiviPlus, but can not receive mail as they are not an inbox.
What are the options for setting up email-to-activity with Gmail?
There are two approaches to get emails from Gmail inboxes processed into CiviPlus via the email-to-activity feature. These can be used in isolation or in tandem, depending on your organisation’s preference.
Note: We recommend using Approach 2 if possible.
Approach 1 - a dedicated Gmail mailbox
For this approach you create a Gmail mailbox with a specific email address (typically organisations choose something like “supportr@yourdomain.com” or similar), which external users can send messages to and you and your team include as a ‘bcc’ when sending any emails from your own Gmail mailboxes.
CiviPlus monitors this mailbox and ingests any new emails that it finds, filing each of them as an Inbound Email activity against the appropriate sender and recipient contacts based on the original To/From email addresses. New contacts will be created if they are not found in CiviPlus.
Note: Ideally this specific mailbox should be a new email address, and not one that already belongs to a team or team member.
Approach 2 - Existing Gmail mailboxes with a dedicated label
For this approach you set up a "label" in your Gmail mailbox which CiviPlus monitors, and simply by tagging messages with the label they will get ingested into CiviPlus and filled as an Inbound or Outbound Email activity against the appropriate sender /recipients based on the To/From email addresses. New contacts can be created if any of the email addresses are not already stored in CiviPlus.
Anyone with access to this IMAP folder within your email client (outside of CiviPlus) will be able to simply drag and drop emails into this folder if they would like them to be processed into CiviPlus as an Email Activity on the relevant contact record(s) in the CRM.
For either approach, once the configuration has been completed CiviPlus will periodically (depending on the frequency set in the scheduled job(s) described below) check the relevant inbox or label and will then create the email activities linked to the contact (or case) records as described above.
To make it clear which Gmail emails have been processed, during the configuration of email-to-Activity processing for a particular mailbox CiviPlus will automatically create two new labels in the mailbox(es) that are to be monitored - CiviMail/ignored and CiviMail/processed.
Each time the Email-to-Activity processing job runs, applicable emails will be moved from their original folder location into one of the above labels where you can view them if needed.
Pros & Cons of Approach 1 and Approach 2
Note: We recommend using Approach 2 if possible.
Approach 1 - App password
Advantages of Approach 1
✔️ Simple to set up: Just IMAP server, username, and app password.
✔️ No need to register apps in Google Cloud
✔️ Good for dedicated mailboxes (e.g., support@, info@).
Disadvantages of Approach 1
❌ Google are phasing out “less secure app” support.
❌ App Passwords are only available if you enable 2-Step Verification.
❌ Less secure than OAuth:
❌ No automatic token rotation.
❌ Can be revoked manually or by security changes on the email account.
Best use case for Approach 1:
✅ Dedicated mailbox that’s only used for CiviPlus processing.
✅ Low maintenance if your org allows app passwords.
Approach 2 - OAUTH authentication
Advantages of Approach 2
✔️ Modern, secure standard.
✔️ Complies with Google’s security policies.
✔️ No passwords stored in CiviPlus database.
✔️ Supports token rotation automatically.
✔️ Survives password changes (as long as you don’t revoke access).
✔️ Required for Google Workspace orgs that block App Passwords.
Disadvantages of Approach 2
❌ More complex to set up:
❌ Requires maintaining the app in Google
❌ May require re-authorisation if refresh tokens expire or are revoked.
❌ Slightly harder for non-technical admins.
Best use case for Approach 2
✅ Gmail mailboxes that require OAuth.
✅ Shared team mailboxes with strict security.
✅ When you want to future-proof your setup.
Configuring Approach 1 - Dedicated mailbox & App password
Before getting started, you will need ensure that you have:
An active Gmail account (ideally specially set up for this purpose)
Access to your Google Account settings
Access to the CiviPlus administration eMail settings
These are the steps to follow
Step 1: Enable IMAP in Gmail (default for personal mailboxes)
Log in to your Gmail account.
Go to Settings > See all settings.
Click Forwarding and POP/IMAP.
In IMAP access, select Enable IMAP.
Save the changes.
Step 2: Create an App Password
Go to your Google Account > Security.
Make sure 2-Step Verification is turned on.
Under Signing in to Google, click App Passwords (or you the direct link here)
Choose provide a suitable App Name and click Create
Google will generate a 16-character password - copy it and use it in the next step below.
Step 3: Configure the Mail Account in CiviPlus
Now we need to configure CiviPlus so that it can access the Gmail mailbox using the App password we just created.
Go to Administer > CiviMail -> Mail Accounts.
Click ADD MAIL ACCOUNT and complete the form
Name - Give this Mail Account a name. It's handy to use the actual name of the mailbox
Server - Enter "imap.gmail.com" for this
Username - Enter the Gmail mailbox address that we will be accessing. In our example this is a personal mailbox called "CiviPlusCRM@gmail.com", but more typically it would be a mailbox in your Google Workspace e.g. CiviPlusCRM@compuco.io
Password - Enter the App Password you created in Step 2 above. Do not use the password for the Gmail account.
Email Domain - Enter "gmail.com" since this is the domain following the @ symbol.
Protocol - Enter IMAP from the drop down list
Used For - Make sure that Email-To-Activity Processing is selected from the drop down list.
Activity Source, Activity Targets, Activity Assignees - Typically you should accept the default values, but you can change the may that email To and From addresses are mapped to CiviPlus Activity roles if your use case demands it.
Now click the SAVE & TEST button
If you have correct configured the new Mail Account you will see a message confirming that CiviPlus could connect to the mailbox, and whether there were any emails ready to be ingested.
Example 1: using BCC to get emails into CiviPlus
In this example Sarah StaffMember sends an email to John Redman from her Gmail account. She is bccing the CiviPlusCRM@gmail.com mailbox, which means her email will be ingested into CiviPlus and an Inbound Email activity will be created, linked to John's contact record as shown below.
An Inbound Email Activity will also be created and linked to Sarah's contact record.
In the CiviPlusCRM mailbox the email has been removed from the inbox and tagged with the INBOX/CiviMail/processed label so that Sarah knows it has been processed.
Configuring Approach 2 - Individual Gmail mailbox with OAUTH
Before getting started, you will need ensure that you have:
An active Gmail account
An active Google Cloud Project
Access to the CiviPlus administration eMail settings
These are the steps to follow
Step 1: Set up a Google Cloud Project
Go to Google Cloud Console.
Create a New Project (or select an existing one).
Name it something like "CiviPlus Email Integration".
Click Create to add the new project to your workspace
Step 2: Configure the OAuth Consent Screen.
You now need to grant your project permission to access Gmail accounts via OAuth.
In the Google Cloud Project, navigate to APIs & Services.
Click Library.
Search for "Gmail API".
Click on the GMAIL API option, and then click the Enable button
Step 3: Create OAuth Client Credentials
Go to APIs & Services > OAuth consent screen.
Click Get Started to configure the Google Auth Platform
Firstly enter an App Name that will access the Gmail mailbox via OAUTH, and a User Support email address of someone who can be contacted if the connection doesn't work. Click Next.
Now select "External" for the Audience if users outside your organisation will authorise it, click Next.
Add an Email address so that Google can contact you if there are any changes to the project.
Click to accept the API Services data usage policy and click Create
In order to actually create the OAUTH credentials you now need to go to the Clients tab on the left of the page, and then click on Create Client.
Select "Web Application" as the Application Type from the drop down list, give it a meaningful Name like "Email2Activity" and add an Authorized Redirect URI:
This URI is where Google will send the OAuth token after authentication.
It must match your CiviPlus site’s expected path
You can validate that it is correct once you have completed the CiviPlus configuration of an Mail Account in step 3 (a) below.
then click Create
Take a note of the Client ID and Client Secret that are generated - you will need them when you configure the CiviPlus Mail Account connection (although you can always retrieve them from the Additional information section of the specific Client ID page).
Click Okay to close the window, and move on to configuring CiviPlus to access the Gmail mailbox using the OAUTH credentials we have just created
Step 4: Add the OAuth Credentials to CiviPlus
Log into your CiviPlus installation
Go to Administer > System Settings > OAuth.
Select the gmail entry, and complete the form:
Make sure that the "Redirect URI" is the same as you entered when configuring the OAUTH client in Google
Enter the Client ID and Client Secret from the Google OAUTH Client credentials setup completed earlier.
Click Add and then Save
Step 5: Authorise the link Your Gmail Account
Go to Administer > CiviMail > Mail Accounts
Click Add Mail Account.
Choose "Google Mail" as the authentication method.
You will asked to select which Google account contains the mailbox that we want to connect to. In this case it is Sarah Staffmember's account:
If you haven't yet published the Google App (i.e. still working in test mode) you will get a message warning you that it hasn't been verified. Click the Continue button.
Next you will asked to confirm the access you will be giving to the App. Click Continue
And now you will be returned to the Mail Account page. Most of the fields will be completed for you and you can use the default values. Note that in this example we have decided to use a specific label (aka folder) to monitor emails, rather than the inbox. This gives Sarah more control over what is ingested by CiviPlus - only those messages that she labels with "Email2Activity" will be stored in CiviPlus.
Click Save and Test, and if CiviPlus is successful in testing the connection to the Gmail mailbox via OAUTH credentials you will see a confirmation message pop up for a few seconds. If not, you will receive a pop up message with some details on what went wrong which you will need to investigate and resolve. See examples of both messages below:
Assuming that the test connection was successful, If Sarah now checks her Gmail mailbox she will see that two sub-labels have been created under the Email2Activity label that she had previous created: CiviMail/Ignored and CiviMail/Processed. When CiviPlus ingests messages they will be moved into one of these two sub-labels depending on what action it takes.
Example 2: Labelling messages to file in CiviPlus
Inbound email example
In this example Sarah StaffMember receives an email from John Redman into her Gmail mailbox. This Mail Account configured inCiviPlus has been set to only file messages that are labelled with "Email2Activity", and so it is only when she labels the email with this "tag" that it will be ingested.
At the time of ingestion. the message will also be labelled as "CiviMail/processed" so that Sarah knows it has been filed into CiviPlus.
Within CiviPlus, since a contact with an email address of RedmanJohn514@gmail.com did not exists a new one was created, and a new Inbound Email activity was linked to this record. Since Sarah Staffmember was already in the system, her existing contact record also had a new Inbound Email activity created and linked.
Outbound email example
When we set up the Mail Account above we said that any messages labelled in SarahStaffmember's mailbox with the Email2Activity tag should be ingested in CiviPlus and a new "Inbound Email" activity created. If we want to differentiate between inbound and outbound messages we can create a second Mail Account in CiviPlus, but this time specify that messages labelled "Email2Activity - Outbound" should have an Outbound Email Activity created.
Once this has been set up, Sarah labels her reply to John as "Email2Activity - Outbound" and so an Outbound Email activity is created in CiviPlus for both Sarah and John, as shown below.
How CiviPlus monitors the Gmail Mailbox
Regardless of the approach that you use to connect to the Gmail, CiviPlus uses a scheduled task that runs periodically to connect to the mailbox(es) and ingest emails. Scheduled tasks are run in CiviPlus by a tool called cron, which we will have set on your system.
To confirm that this particualar task is enabled navigate to Administer -> System Settings -> Scheduled Jobs. You will see the Process Inbound Emails job listed, with the frequency that it runs.
You can change the frequency of the polling by editing the Scheduled Job.
Note: You may not have access to the Scheduled Jobs page, in which case you can check with Compuco to ensure that the Process Inbound Emails job is enabled and the frequency that it will run.
Case management email processing
If you are using CiviCase, the eMail to Activity feature can also file emails against a Case as well as a contact record. To do this the email subject needs to include the Case ID in the format "[case #ID]", for example
[case #123123]
[case #asdasd9a0sdajasd]
To help someone external knows what the Case ID is you can send an email from within the Case and use the Case ID token in the subject line. Then if they reply the subject line will already have the syntax that is needed, for example, in the email below the part of the subject line with the token in it "[case #{case.id}]" will be replaced by "[case #abdd828]" when the email is sent to John.
When if John replies or forwards the email to a Gmail mailbox that has an Mail Account set up for it (in this case sarastaffmember@gmail.com, as described in Approach 1 and Approach 2 above), and if the subject line includes "[case #abdd828]" then the email will be filed against the appropriate Case, as shown below:
Please note, that if you are using more than one ‘Case Management’ dashboard within CiviPlus, currently the Email to Activity feature is only supported for the original dashboard.
Options for the way that the Gmail ingestion works
There are some configuration options available that change the way that Gmail messages are ingested into CiviPlus as activities.
Do you want the system to create new contact records if it can’t find an existing contact with the same email address?
By default, the system will create a new contact, but this can be prevented if you would prefer (many clients prefer this option).
Do you want the status of the new email Activity created set to "Completed"?
By default, the system will set the status of processed email activities to "Completed". If this doesn’t suit your internal workflows, we can alternatively set the default to be another of the available activity statuses.
Do you want to ensure that emails are only filed to the CRM in the context of case management?
You can configure the Mail Account to ignore emails that do not have a valid Case ID in the subject line.
Do you want to use Approach 1 (above), Approach 2 (above), or both?