Basic Setup

To set up a new Gmail or G Suite channel in Zammad, you first have to create an OAuth app in Google’s Cloud console. Then you can connect Zammad with your Google account and add as many Gmail accounts to Zammad as you want, using only active Gmail browser sessions (no usernames or passwords required).

If you already set up Google email channels in Zammad, you can easily migrate them to a Google channel. Follow the steps below but skip the step “Add Account” and proceed with Migrate from Email Channel.

Register an OAuth App

Sign in to the Google Cloud console. You should see a dashboard where you can add a new project. If you already have an app which is in production, create a new one and follow the steps below.

Create an OAuth Consent Screen

In the left sidebar of your project’s “APIs & Services” section, select OAuth consent screen and provide the requested information.

In the first screen, select “Internal” as User Type and click on “Create”.

Provide the following information in the next screen:

• App name: enter a suitable name for this app

• User support email: select an email address from the dropdown

• Authorized domain: the domain of your Zammad without http or https prefix

• Developer contact information: enter a valid email address

After entering the information, click on “Save and Continue”. You should be on the “Scopes” screen. Click on “Add or Remove Scopes” to see the dialog as in the following screenshot.

1. Enter https://mail.google.com in the “Manually add scopes” text field

2. Click on “Add to Table” to have it in the selectable scopes table above

3. Select it by checking the box

4. Confirm by clicking the “Update” button

Go on by clicking “Save and Continue”. If your app is in “Testing” mode, add a user as which you want to sign in to your Google account. After that you see a summary screen where you can check the information. Confirm by clicking the “Back to Dashboard” button and go on with creating credentials for your app.

Create Credentials

Select “Credentials” in the left sidebar, click on “➕ Create Credentials” and choose “OAuth client ID”.

Select “Web application” as Application type, give it a name and enter your redirect URL.

The redirect URL is basically the domain of your Zammad instance, extended with /api/v1/external_credentials/google/callback.

You can even find the complete redirect URL in Zammad’s admin area under Channels > Google. Click on “Configure App” and find your URL under “Your callback URL”.

Click on “Create” after inserting the information. You will see a dialog with your client ID and client secret. You need both of them in the next step for configuring Zammad to connect it to Google.

Configure App

Go to Channels > Google in Zammad’s admin area and click on “Configure App”. Insert the client ID and client secret which you got in the step before.

Confirm by clicking the “Submit” button. Now you can add a Google account as channel in Zammad, see next step.

Add Account

If you already have Google email channels, you can skip this step and head over to Migrate from Email Channel.

After you’ve registered Zammad as an OAuth app, you can connect Gmail accounts to Zammad.

☠️ But first, a word of warning! The import process does things you might not expect:

Danger

• By default, Zammad will delete all emails in your inbox during the import process. Use the Keep Messages on Server setting to disable this behavior.

• Zammad will send an auto-reply message to every email it imports (including the old ones!). Make sure to disable this behavior prior adding an email account and to turn it back on once all your messages have been imported.

To connect you Google account, click on “Add Account” in Zammad. You will be redirected to a consent dialog. Click through the screens and and make sure to select the desired Google account as well as to grant the permission for email handling as you can see in the following screenshot.

After clicking on “Continue”, you are redirected to Zammad where you can see a dialog for specifying a folder and if you want to keep messages on the server.

Folder

Specify which folder (or label) to fetch from, or leave empty to fetch from INBOX. If specifying a nested folder, be sure to use the full path, e.g. Inquiries/Tech-Support.

Keep messages on server

Specify what happens to your emails after Zammad imports them:

• no: Zammad deletes all imported messages

• yes: Zammad marks imported messages as read. With this option, Zammad will only import unread messages. This means Zammad may miss messages if the mailbox is externally modified.

Note

🤔 Why does Zammad delete messages by default?

If you never clean out your inbox, it’ll eventually reach its storage limit, and your mail server will start rejecting incoming messages. Most Zammad users never even look at their inbox once it’s set up, so they rely on Zammad to keep it clean for them.

If you choose yes here, remember that it’s your responsibility to clean out your inbox from time to time to keep it below its storage limit.

After successfully adding the Google account, you can adjust the default group Zammad is going to assign incoming new tickets to.

Only active groups will be displayed. Changing this setting will not reassign existing tickets to the new group.

Migrate from Email Channel

Convert Email Channel to Google Channel

Zammad provides a migration logic that allows you to migrate existing Google accounts from an email channel into a Google channel.

Note

🧐 Zammad is expecting specific settings

In order for Zammad to display the migration option, it expects the channels hostname to be imap.gmail.com for IMAP and smtp.gmail.com for SMTP.

The easiest way to start the migration is to Register an OAuth App for your Google accounts before migrating. However, if you don’t, Zammad will ask you to provide your app credentials before allowing you to continue.

If you’re ready to go, simply click on the Migrate now! button in the red banner of the email channel in question. Zammad will redirect you to Google and request you to authenticate and consent to said account.

After you pressed next you’ll be redirect to Zammad’s Google channel overview. Your channel, if successful, is now migrated to an Google channel.

Rolling Back the Migration

In case something went wrong, Zammad allows you to roll back the migration for up to 7 days. For this time period Zammad will remember your original credentials and restore it if needed. These information will be removed entirely after 7 days.

Troubleshooting

My OAuth credentials stopped working

Did you recently change your Google password? Google invalidates all your OAuth tokens whenever you change it.

How to use the Gmail account for outgoing system notifications?

On subscription/cloud-hosted instances, you can’t do that. Notifications will always come from “Notification Master <noreply@your.zammad.domain>”.

On self-hosted instances, we still don’t recommend it. Using a Gmail account for automated, outgoing messages is risky: users who exceed Google’s email sending limits can have their accounts suspended.

Set up a generic email channel instead and use the Email Notification setting.

I successfully added my account, but Zammad isn’t fetching new emails

If you specified a custom folder/label to fetch from, are you sure incoming mail is arriving in that folder?